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PREFACE 


This  manual  describes  the  use  of  the  RT-11  Operating  System,  including 
both  Single- Job  and  Foreground/Background  monitors.  It  assumes  that 
the  user  has  had  some  exposure  to  assembly  language  programming  and 
computer  systems  in  general.  For  definitions  of  the  technical 
terminology  used  within  the  documentation,  consult  the  Glossary  at  the 
end  of  the  manual.  In  addition,  the  introductory  chapters  of  the 
PDP-11  PAPER  TAPE  SOFTWARE  PROGRAMMING  HANDBOOK  (DEC-ll-XPTSA-A-D) , 
the  PDP-11  PROCESSOR  HANDBOOK,  and  the  PDP-11  PERIPHERALS  HANDBOOK  can 
also  be  consulted  for  reference  purposes.  The  "Getting  Started  With 
RT-11"  document  (DEC— 11— ORCPA— D— D)  included  with  each  system  provides 
a  basic  introduction  to  RT-11;  by  following  the  instructions  in  its 
demonstration,  the  user  can  become  acquainted  with  RT-11  operating 
procedures. 

Upon  receiving  the  RT-11  system  it  is  recommended  that  the  user  first 
read  through  the  entire  manual  to  become  familiar  with  system 
conventions.  The  concepts  of  the  system  will  become  clear  if  the 
manual  is  read  in  its  entirety  first  for  a  general  introduction  to 
RT-11  as  a  whole,  and  then  reread  for  specific  information. 

Chapters  1  and  2  discuss  general  system  operations  and  monitor 
keyboard  commands  used  to  control  jobs  and  to  implement  user  programs . 
System  programs  (EDIT,  PIP,  MACRO,  LINKER,  LIBR,  ODT)  are  described  in 
Chapters  3  through  8.  Chapter  9  describes  programmed  requests;  this 
chapter  will  be  of  particular  interest  to  the  experienced  programmer 
who  wishes  to  make  use  of  monitor  services  in  his  own  assembly 
language  programs.  Chapters  10  and  11  explain  the  8K  Assembler  and 
EXPAND  programs  which  are  most  useful  in  RT-11  systems  with  minimum 
memory  configurations.  The  appendixes  summarize  the  contents  of  the 
manual  and  introduce  several  additional  utility  programs  used  for 
various  non-standard  system  operations  (FILEX,  SRCCOM,  PATCH,  DUMP). 

All  programs  discussed  in  the  manual  may  be  used  in  any  Single-job  or 
Foreground/Background  environment  with  the  exception  of  the  MACRO 
assembler  (Chapter  5) ,  which  requires  a  minimum  of  12K  of  memory  for 
execution,  and  with  the  exception  of  certain  monitor  commands  that  can 
be  used  only  in  a  F/B  environment  (see  Chapter  2,  Section  2.7.5). 

This  manual  describes  RT-11  Version  2  software  (identification  numbers 
are  usually  produced  via  a  specific  command  in  each  program,  or  are 
part  of  the  header  in  the  listing  produced  by  the  program;  see  the 
appropriate  chapter  or  appendix) : 
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Program 

Version  2 

Ident i f icat ion 

Version  1 
Identification 

Single- Job  Monitor 

VO  2- 01 

V0 1-15 

F/B  Monitor 

VO 2- 01 

N/A 

EDIT 

VO  2- 02 

V0 1-24 

PIP 

V02-02 

V01-06 

MACRO 

VM02-09 

VM01-01 

CREF 

VO  1-02 

N/A 

LINK 

VO  3- 01 

V0 1-04 

LIBR 

V02-01 

N/A 

ODT 

V0 1-01 

V0 1-01 

EXPAND 

V0  2- 02 

V01 

ASEMBL 

VS02-09 

VS01-01 

FILEX 

V0 1-01 

N/A 

SRCCOM 

V0 1-01 

N/A 

DUMP 

V0 1-01 

N/A 

PATCH 

V0 1-02 

V01-01 

PATCHO 

V01-02 

N/A 

RT-11  Version  2  is  compatible  with  RT-11  Version  1  with  respect  to  the 
following: 

1.  Version  1  source  programs  will  assemble  properly  under 
Version  2  (the  OBJ  modules  are  compatible) . 

2.  Version  1  save  image  files  which  conform  to  RT-11  programming 
rules  (see  Chapter  9  and  Appendix  H)  will  execute  correctly 
under  Version  2. 

Differences  between  the  two  systems  include: (1) 

1.  Revised  device  handler  and  interrupt  interfaces  have  been 
written  for  Version  2  (see  Appendix  H) . 

2.  Stricter  rules  for  the  .SETTOP  request  must  be  observed  in 
Version  2  (see  Chapter  9). 

3.  Additional  monitor  commands  are  available  in  Version  2,  with 
extension  of  some  of  the  pre-existing  commands  (see  Chapter 
2). 

Additional  features  available  in  Version  2  and  not  in  Version  1 
include : 

1.  Support  of  RF  fixed-head  disk,  card  reader,  magtape,  cassette 
and  display  hardware 

2.  Foreground/Background  Monitor  (including  timer  support) 


(1)  See  Chapter  5  in  "Getting  Started  With  RT-11"  (DEC-11-0RCPA-D-D) 
for  a  comprehensive  list  of  differences  between  the  two  systems. 
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3.  Extended  programmed  requests 

4.  New  utilities,  including  CREF,  LIBR,  FILEX,  SRCCOM,  DUMP, 
PATCHO,  and  optionally,  FORTRAN  IV, 

In  general,  if  the  user  is  already  familiar  with  RT-11,  Version  1,  he 
may  omit  reading  the  following  chapters,  since  the  technical 
information  has  not  changed: 


Chapter 

3  - 

EDIT 

(with 

Chapter 

5  - 

MACRO 

(with 

Chapter 

8  - 

ODT 

(note 

Chapter  10  - 

EXPAND 

Chapter 

11  - 

ASEMBL 

Appendix 

L  - 

PATCH 

Section  3.7) 
Section  5.7) 
in  Section  8.1) 


The  remainder  of  the  manual  should  be  read  in  its  entirety.  The  user 
should  not  assume  that  knowledge  of  Version  1  is  sufficient  for  use  of 
Version  2. 


Three  additional  manuals  describe  the  capabilities  of  the  optional 
RT-11  system  components: 

1.  BASIC/RT-11  LANGUAGE  REFERENCE  MANUAL  (DEC-ll-LBACA-C-D-D) 

2.  PDP-11  FORTRAN  LANGUAGE  REFERENCE  MANUAL  (DEC-ll-LFLRA— A— D) 

3.  RT-11  FORTRAN  COMPILER  AND  OBJECT  TIME  SYSTEM  USER'S  MANUAL 
( DEC-ll-LRFPA-A-D) 


These  manuals  can  be  ordered  from  the  Digital  Software  Distribution 
Center.  Summaries  of  the  features  provided  by  each  language  appear  in 
this  manual  in  Appendixes  F  and  G  respectively. 

Two  PDP-11  system  manuals  may  be  helpful  when  using  FILEX  (Appendix  J) 
to  convert  programs  between  DOS,  RSTS-11  and  RT-11  formats: 

1.  PDP-11  RESOURCE  SHARING  TIME-SHARING  SYSTEM  USER'S  GUIDE 
(DEC-11-0RSUA— A— D) 

2.  PDP-11  DISK  OPERATING  SYSTEM  MONITOR  PROGRAMMER'S  HANDBOOK 
(DEC— 11— OMONA— A— D) 

Users  of  display  hardware  may  wish  to  refer  to  the  appropriate 
hardware  manual:  vr  r 

1.  GT40  USER'S  GUIDE  (DEC-ll-HGTGA-A-D) 

2.  GT44  USER'S  GUIDE  (DEC-11-HGT44-A-D) 

3.  VT11  GRAPHIC  DISPLAY  PROCESSOR  MANUAL  (DEC-ll-HVTGA-A-D) 

4.  VT50  VIDEO  TERMINAL  PROGRAMMER'S  MANUAL  (DEC-OO-OVTSA-A-D) . 

Conventions  used  throughout  this  manual  include  the  following: 

1#  ^5tual  comPuter  output  is  used  in  examples  wherever  possible. 
When  necessary,  computer  output  is  underlined  to 

differentiate  from  user  responses. 
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2.  To  avoid  confusion ,  a  line  feed  (character  or  key)  is 
represented  in  the  text  as  <LF>?  a  carriage  return  (character 
or  key)  is  represented  as  <CR>.  Unless  otherwise  indicated, 
all  commands  and  command  strings  are  terminated  by  a  carriage 
return, 

3.  Terminal,  console  terminal,  and  teleprinter  are  general  terms 

used  throughout  the  documentation  to  represent  any  one  of  the 
following:  LA30  or  LA36  DECwriter,  VT05  or  VT50  Display, 

LT33  or  LT35  Teletype (2). 

4.  Several  characters  in  system  commands  are  produced  by  typing 
a  combination  of  keys  concurrently?  for  example,  the  CTRL 
key  is  held  down  while  typing  an  0  to  produce  a  command  which 
causes  suppression  of  teleprinter  output.  Key  combinations 
such  as  this  are  documented  as  CTRL  0,  CTRL  C,  SHIFT  N,  and 
so  forth. 


(2)  Teletype  is  a  registered  trademark  of  the  Teletype  Corporation. 
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CHAPTER  1 


RT-11  OVERVIEW 


RT-11  is  a  single-user  programming  and  operating  system  designed  for 
the  PDP-11  series  of  computers.  This  system  permits  the  use  of  a  wide 
range  of  peripherals  and  up  to  28K  of  either  solid  state  or  core 
memory  (hereafter  referred  to  as  memory) . 

RT-11  provides  two  operating  environments:  Single-Job  operation,  and 
a  powerful  Foreground/Background  (F/B)  capability (1) . 

Single-Job  operation  allows  only  one  program  to  reside  in  memory  at 
any  time;  execution  of  the  program  continues  until  either  it  is 
completed  or  it  is  physically  interrupted  by  the  user  at  the 
console. 

In  a  Foreground/Background  environment,  two  independent  programs  may 
reside  in  memory.  The  foreground  program  is  given  priority  and 
executes  until  it  relinquishes  control  to  the  background  program;  the 
background  program  is  allowed  to  execute  until  control  is  again 
required  by  the  foreground  program,  and  so  on.  This  sharing  of  system 
resources  greatly  increases  the  efficiency  of  processor  usage. 

To  handle  both  operating  environments,  RT-11  offers  two  completely 
compatible  and  versatile  monitors  (Single- job  and  F/B) ;  either  monitor 
provides  complete  user  control  of  the  system  from  the  console  terminal 
keyboard.  Monitor  commands  which  allow  the  user  to  direct  single- job, 
foreground,  and  background  operations  are  described  in  Chapter  2. 

In  addition  to  the  monitor  facilities,  RT-11  offers  a  full  complement 
of  system  programs;  these  allow  program  development  using  high  level 
languages  such  as  FORTRAN  IV  and  BASIC  or  assembly  language  (MACRO  or 
EXPAND/ASEMBL) •  System  programs  are  summarized  in  Section  1.2  and  are 
discussed  in  detail  in  individual  chapters  and  appendixes  of  this 
manual. 


(1)  The  uses  and  advantages  of  each  environment  are  outlined  later  in 
this  chapter. 
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1.1  PROGRAM  DEVELOPMENT 

Computer  systems  such  as  RT-11  are  often  used  extensively  for  program 
development.  The  programmer  makes  use  of  the  programming  "tools" 
available  on  his  system  to  develop  programs  which  will  perform 
functions  specific  to  his  needs.  The  number  and  type  of  "tools” 
available  on  any  given  system  depend  on  a  good  many  factors — the  size 
of  the  system,  its  application  and  its  cost,  to  name  a  few.  Most 
Digital  systems,  however,  provide  several  basic  program  development 
aids:  these  generally  include  an  editor,  assembler,  linker,  debugger, 
and  often  a  librarian;  a  high  level  language  (such  as  FORTRAN  IV  or 
BASIC)  is  also  usually  available. 

An  editor  is  used  to  create  and  modify  textual  material.  Text  may  be 
the  lines  of  code  which  make  up  a  source  program  written  in  some 
programming  language,  or  it  may  be  data;  text  may  be  reports,  or 
memos,  or  in  fact  may  consist  of  any  subject  matter  the  user  wishes. 
In  this  respect  using  an  editor  is  analogous  to  using  a 
typewriter — the  user  sits  at  a  keyboard  and  types  text.  But  the 
advantages  of  an  editor  far  exceed  those  of  a  typewriter  because  once 
text  has  been  created,  it  can  be  modified,  relocated,  replaced, 
merged,  or  deleted — all  by  means  of  simple  editing  commands.  When  the 
user  is  satisfied  with  his  text,  he  can  save  it  on  a  storage  device 
where  it  is  available  for  later  reference. 

If  the  editor  is  used  for  the  purpose  of  writing  a  source  program, 
development  does  not  stop  with  the  creation  of  this  program.  Since 
the  computer  cannot  understand  any  language  but  machine  language 
(which  is  a  set  of  binary  command  codes) ,  an  intermediary  program  is 
necessary  which  will  convert  source  code  into  the  instructions  the 
computer  can  execute.  This  is  the  function  of  an  assembler. 

The  assembler  accepts  alphanumeric  representations  of  PDP-11  coding 
instructions  (i.e.,  mnemonics),  interprets  the  code,  and  produces  as 
output  the  appropriate  object  code.  The  user  can  direct  the  assembler 
to  generate  a  listing  of  both  the  source  code  and  binary  output,  as 
well  as  more  specific  listings  which  are  helpful  during  the  program 
debugging  process.  In  addition,  the  assembler  is  capable  of  detecting 
certain  common  coding  errors  and  of  issuing  appropriate  warnings. 

The  output  produced  by  the  assembler  is  called  object  output  because 
it  is  composed  of  object  (or  binary)  code.  On  PDP-11  systems,  the 
object  output  is  called  a  module  and  contains  the  user's  source 
program  in  the  binary  language  which  is  acceptable  to  a  PDP-11 
computer . 

Source  programs  may  be  complete  and  functional  by  themselves; 
however,  some  programs  are  written  in  such  a  way  that  they  must  be 
used  in  conjunction  with  other  programs  (or  modules)  in  order  to  form 
a  complete  and  logical  flow  of  instructions.  For  this  reason  the 
object  code  produced  by  the  assembler  must  be  relocatable — that  is, 
assignment  of  memory  locations  must  be  deferred  until  the  code  is 
combined  with  all  other  necessary  object  modules.  It  is  the  purpose 
of  linker  to  perform  this  relocation. 

The  linker  combines  and  relocates  separately  assembled  object 
programs.  The  output  produced  by  the  linker  consists  of  a  load 
module,  which  is  the  final  linked  program  ready  for  execution.  The 
user  can,  at  his  option,  request  a  load  map  which  displays  all 
addresses  assigned  by  the  linker. 
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Very  rarely  is  a  program  created  which  does  not  contain  at  least  one 
unintentional  error,  either  in  the  logic  of  the  program  or  in  its 
coding.  Errors  may  be  discovered  by  the  programmer  while  he  is 
editing  his  program,  or  the  assembler  may  find  errors  during  the 
assembly  process  and  inform  the  programmer  by  means  of  error  codes. 
The  linker  may  also  catch  certain  errors  and  issue  appropriate 
messages.  Often,  however,  it  is  not  until  execution  that  the  user 
discovers  his  program  is  not  working  properly.  Programming  errors  may 
be  extremely  difficult  to  find,  and  for  this  reason  a  debugging  tool 
is  usually  available  to  aid  the  programmer  in  determining  the  cause  of 
his  error. 

A  debugging  program  allows  the  user  to  interactively  control  the 
execution  of  his  program.  With  it,  he  can  examine  the  contents  of 
individual  locations,  search  for  specific  bit  patterns,  set  designated 
stopping  points  during  execution,  change  the  contents  of  locations, 
continue  execution,  and  test  the  results,  all  without  the  need  of 
re-editing  and  re-assembling. 

When  programs  are  successfully  written  and  executed,  they  may  be 
useful  to  other  programmers.  Often  routines  which  are  common  to  many 
programs  (such  as  I/O  routines)  or  sections  of  code  which  are  used 
over  and  over  again,  are  more  useful  if  they  are  placed  in  a  library 
where  they  can  be  retrieved  by  any  interested  user.  A  librarian 
provides  such  a  service  by  allowing  creation  of  a  library  file.  Once 
created,  the  library  can  be  expanded,  updated,  or  listed. 

High  level  languages  simplify  the  programmer's  work  by  providing  an 
alternate  means  of  writing  a  source  program  other  than  assembly 
language  mnemonics.  Generally,  high  level  languages  are  easy  to 
learn— a  single  command  may  cause  the  computer  to  perform  many  machine 
language  instructions.  The  user  does  not  need  to  know  about  the 
mechanics  of  the  computer  to  use  a  high  level  language.  In  addition, 
some  high  level  languages  (like  BASIC)  offer  a  special  immediate  mode 
which  allows  the  user  to  solve  equations  and  formulas  as  though  he 
were  using  a  calculator.  Assembling  and  linking  are  done 
automatically  so  that  the  user  can  concentrate  on  solving  the  problem 
rather  than  using  the  system. 

These  are  a  few  of  the  programming  tools  offered  by  most  computer 
systems.  The  next  section  summarizes  specific  programming  aids 
available  to  the  user  of  RT-11. 


1.2  SYSTEM  SOFTWARE  COMPONENTS 

The  following  is  a  brief  summary  of  the  RT-11  system  programs: 

1.  The  Text  Editor  (EDIT,  described  in  Chapter  3)  is  used  to 
create  or  modify  source  files  for  use  as  input  to  language 
processing  programs  such  as  the  assembler  or  FORTRAN.  EDIT 
contains  powerful  text  manipulation  commands  for  quick  and 
easy  editing  of  a  text  file.  EDIT  also  allows  use  of  a  VT-11 
display  processor  (such  as  the  GT44) ,  if  one  is  part  of  the 
hardware  configuration  (see  Section  1.3). 

2.  The  MACRO  Assembler  (Chapter  5)  brings  the  capabilities  of 
macros  to  the  RT-11  system  with  12K  (or  more)  memory. 
(Macros  are  instructions  in  a  source  or  command  language 
which  are  equivalent  to  a  specified  sequence  of  machine 
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instructions  or  commands.)  The  assembler  accepts  source  files 
written  in  the  MACRO  language  and  generates  a  relocatable 
object  module  to  be  processed  by  the  Linker  before  loading 
and  execution.  Cross  reference  listings  of  assembled 
programs  may  be  produced  using  CREF  in  conjunction  with  the 
MACRO  Assembler. 

3.  EXPAND  (Chapter  10)  is  used  in  an  8K  F/B  job  area  or  8K 

systems  (or  in  larger  systems  with  programs  of  great  size)  to 
expand  macros  in  an  assembly  language  program  into  macro-free 
source  code,  thus  allowing  the  program  to  be  assembled  in  8K 
using  ASEMBL. 

4.  ASEMBL  (Chapter  11)  is  an  assembler  designed  for  use  in  an  8K 

RT-11  system,  an  8K  F/B  job  area,  or  larger  systems  where 

symbol  table  space  is  a  factor.  ASEMBL  is  a  subset  of 

MACRO-11  with  more  limited  features.  (CREF  is  not  available 
under  ASEMBL.) 

5.  The  Linker  (LINK,  described  in  Chapter  6)  fixes  (i.e.,  makes 
absolute)  the  values  of  relocatable  symbols  and  converts  the 
relocatable  object  modules  of  compiled  or  assembled  programs 
and  subroutines  into  a  load  module  which  can  be  loaded  and 
executed  by  RT-11.  LINK  can  automatically  search  library 
files  for  specified  modules  and  entry  points;  it  can  produce 
a  load  map  (which  lists  the  assigned  absolute  addresses)  and 
can  provide  automatic  overlay  capabilities  to  very  large 
programs.  The  Linker  can  also  produce  files  suitable  for 
running  in  the  foreground. 

6.  The  Librarian  (LIBR,  see  Chapter  7)  allows  the  user  to  create 
and  maintain  his  own  library  of  functions  and  routines. 
These  routines  are  stored  on  a  random  access  device  as 
library  files,  where  they  can  be  referenced  by  the  Linker. 

7.  The  Peripheral  Interchange  Program  (PIP,  see  Chapter  4)  is 
the  RT-11  file  maintenance  and  utility  program.  It  is  used 
to  transfer  files  between  all  devices  which  are  part  of  the 
RT-11  system,  to  rename  or  delete  files,  and  to  obtain 
directory  listings. 

8.  SRCCOM  (Source  Compare,  described  in  Appendix  K)  allows  the 
user  to  perform  a  character-by-character  comparison  of  two  or 
more  text  files.  Differences  can  be  listed  in  an  output  file 
or  directly  on  the  line  printer  or  terminal,  thus  providing  a 
fast  method  of  determining,  for  example,  if  all  edits  to  a 
file  have  been  correctly  made. 

9.  FILEX  (Appendix  J)  allows  file  transfers  to  occur  between 
DECtapes  used  under  the  DECsystem— 10  or  PDP-11  RSTS  system, 
and  DECtape  and  disk  used  under  the  DOS/BATCH  system,  and  any 
RT-11  device. 

10.  The  PATCH  utility  program  (Appendix  L)  is  used  to  make  minor 
modifications  to  memory  image  files  (output  files  produced  by 
the  Linker) ?  it  is  used  on  files  which  do  or  do  not  have 
overlays.  PATCHO  (Appendix  M)  is  used  to  make  minor 
modifications  to  files  in  object  format  (output  files 
produced  by  the  FORTRAN  compiler  and  the  Librarian,  or  MACRO 
and  ASEMBL  assemblers) . 
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11.  ODT  (On-line  Debugging  Technique,  described  in  Chapter  8) 
aids  in  debugging  assembled  and  linked  object  programs.  It 
can  print  the  contents  of  specified  locations,  execute  all  or 
part  of  the  object  program,  single  step  through  the  object 
program,  and  search  the  object  program  for  bit  patterns. 

12.  DUMP  (Appendix  I)  is  used  to  print  for  examination  all  or  any 
part  of  a  file  in  octal  words,  octal  bytes,  ASCII  and/or 
RAD50  characters  (see  Chapter  5). 

BASIC  and  FORTRAN  IV  are  two  high  level  languages  available  under 
RT-11.  Summaries  of  their  language  features  and  commands  are  provided 
in  Appendixes  F  and  G  of  this  manual. 


1.3  SYSTEM  HARDWARE  COMPONENTS 

The  minimum  RT-11  system  (that  is,  one  that  does  not  use  the  F/B 
capability)  requires  a  PDP-11  series  computer  with  at  least  8K  of 
memory,  a  random  access  device  and  a  console  terminal.  To  use  the 
GT  ON  and  GT  OFF  monitor  commands,  a  system  configuration  of  at  least 
12K  is  required.  If  the  F/B  capability  is  to  be  used,  at  least  16K  of 
memory  and  a  line  frequency  clock  are  required. 

The  following  are  optional  hardware  devices  supported  by  the  RT-11 
system: 

RK05/RK11 ,  RF11/RS11  disk 
TC11/TU56  DECtape 
Display  Processor  (VT11) 

Line  Printer  (LP11,  LS11,  or  LV11) 

Card  Reader  (CR11,  CM11) 

Terminal  (LA30/LA36,  VT05,  VT50  or  LT33/LT35) 

PC11  High-speed  Reader/Punch 
TM11/TU10  Magtape 
TA11/TU60  Cassette 


RT-11  operates  in  environments  ranging  from  8K  to  28K  words  of  memory. 
Reconfiguration  for  different  memory  sizes  is  unnecessary— the  same 
system  device  operates  on  any  PDP-11  processor  with  8K  to  28K  of 
memory  and  makes  use  of  all  memory  available. 


1-5 


i 


RT-11  Overview 


1.4  USING  THE  RT-11  SYSTEM 

As  mentioned  earlier  in  the  chapter ,  the  RT-11  system  offers  two 
complete  operating  environments.  Each  is  controlled  by  a  single  user 
from  the  console  terminal  keyboard  by  means  of  an  appropriate 
monitor — Single-Job  or  Foreground /Background.  Both  monitors  are 
completely  compatible  and  allow  full  user  interaction  with  all 
features  which  are  a  part  of  the  operating  environment  in  use. 

The  choice  of  which  environment  to  use,  and,  consequently,  which 
monitor  to  run,  depends  upon  the  needs  of  the  user.  The  next  two 
sections  provide  information  useful  in  determining  which  monitor  is 
more  suitable  for  certain  applications. 


1.4.1  RT-11  Single- Job  Monitor 

The  RT-11  Single- Job  Monitor  provides  a  single-user,  single-program 
system  which  can  operate  in  as  little  as  8K  of  memory.  Since  the 
Single-Job  Monitor  itself  requires  approximately  one-half  the  memory 
space  needed  by  the  Foreground/Background  Monitor,  this  system  is 
ideal  for  extensive  program  development  work;  a  much  larger  area  of 
memory  is  available  for  the  user  program  and  its  buffers  and  tables. 
Programs  requiring  extremely  high  data  rates  are  best  run  in  the 
Single- Job  environment,  since  interrupts  can  be  serviced  at  a  much 
higher  rate. 

All  system  programs  (listed  in  Section  1.2)  can  be  used  under  the 
Single- Job  Monitor,  and  many  of  the  features  of  the 
Foreground/Background  Monitor  (i.e.,  KMON  commands  and  programmed 
requests  not  used  to  control  foreground  jobs)  are  supported. 

In  effect,  the  Single-Job  Monitor  is  much  smaller  and  slightly  faster 
than  the  Foreground/Background  Monitor;  it  can  best  be  used  when 
program  size  is  the  important  factor. 


1.4.2  RT-11  Foreground/Background  Monitor 

Quite  often  the  central  processor  of  a  computer  system  may  spend  a 
large  percentage  of  time  waiting  for  some  external  event  to  occur,  the 
most  common  event  being  the  completion  of  an  I/O  transfer  (this  is 
particularly  true  of  real  time  jobs).  Many  users  would  like  to  take 
advantage  of  this  unused  capacity  to  accomplish  other  lower-priority 
tasks  such  as  further  program  development  or  complex  data  analysis. 
The  Foreground/Background  system  provides  this  capability. 

In  a  Foreground/Background  system  the  foreground  job  is  the 
time-critical,  on-line  job,  and  is  given  top  priority;  whenever 
possible  the  processor  runs  the  foreground  job.  However,  when  the 
foreground  job  reaches  a  state  in  which  no  more  processing  can  be  done 
until  some  external  event  occurs,  the  monitor  will  try  to  run  the 
lower  priority  background  job.  The  background  job  then  runs  until  the 
foreground  job  is  again  in  a  runnable  state,  at  which  point  the 
processor  will  interrupt  the  background  job  and  resume  the  foreground 
job. 

In  general,  the  RT-11  Foreground/Background  System  is  designed  to 
allow  a  time-critical  job  to  run  in  the  foreground,  while  the 
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background  does  non-time-critical  jobs,  such  as  program  development. 
(All  RT-11  system  programs  run  as  the  background  job  in  a  F/B  system.) 
Thus,  the  user  can  run  FORTRAN,  BASIC,  MACRO,  etc.  in  the  background 
while  the  foreground  may  be  collecting  data  and  storing  and/or 
analyzing  it. 

Most  user  programs  written  for  an  RT-11  System  can  be  linked  (using 
the  Linker  described  in  Chapter  6)  to  run  as  the  foreground  job. 
There  are  a  few  coding  restrictions,  and  these  are  explained  in 
Appendix  H,  F/B  Programming  and  Device  Handlers.  A  foreground  program 
has  access  to  all  of  the  features  available  to  the  background  job 
(opening  and  closing  files,  reading  and  writing  data,  etc.).  In 
addition,  the  F/B  System  gives  the  user  the  ability  to  set  timer 
routines,  suspend  and  resume  F/B  jobs,  and  send  data  and  messages 
between  the  two  jobs. 


1.4.3  Facilities  Available  Only  in  RT-11  F/B 

As  mentioned  previously,  RT-11  F/B  allows  the  user  to  write  and 
execute  two  independent  programs.  Some  features  which  are  available 
only  to  the  F/B  user  include: 

1.  Mark  Time— This  facility  allows  user  programs  to  set  clock 
timers  to  run  for  specified  amounts  of  time.  When  the  timer 
runs  out,  a  routine  specified  by  the  user  is  entered.  There 
may  be  as  many  mark  time  requests  as  desired,  providing 
system  queue  space  is  reserved  (see  .QSET,  Chapter  9). 

2.  Timed  Walt— This  feature  allows  the  user  program  to  "sleep" 
until  the  specified  time  increment  elapses.  Typically,  a 
program  may  need  to  sample  data  every  few  seconds  or  even 
minutes.  While  the  program  is  idle,  the  other  job  can  run. 
The  timed  wait  accomplishes  this;  when  the  time  has  elapsed, 
the  issuing  job  is  again  runnable  (see  .TWAIT,  Chapter  9). 

3.  Send  Data/Receive  Data — It  is  possible,  under  RT-11  F/B,  to 
have  the  foreground  and  background  programs  communicate  with 
one  another.  This  is  accomplished  with  the  send/receive  data 
functions.  Using  this  facility,  one  program  sends  messages 
(or  data)  in  variable  size  blocks  to  the  other  job.  This  can 
be  used,  for  example,  to  pass  data  from  a  foreground 
collection  program  directly  to  a  background  analysis  program 
(see  .SDAT/.RCVD,  Chapter  9). 
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CHAPTER  2 

SYSTEM  COMMUNICATION 


The  monitor  is  the  hub  of  RT-11  system  communications;  it  provides 
access  to  system  and  user  programs,  performs  input  and  output 
functions,  and  enables  control  of  background  and  foreground  jobs. 

The  user  communicates  with  the  monitor  through  programmed  requests  and 
keyboard  commands.  The  keyboard  commands  (described  in  Section  2.7) 
are  used  to  load  and  run  programs,  start  or  restart  programs  at 
specific  addresses,  modify  the  contents  of  memory,  and  assign  and 
deassign  alternate  device  names. 

Programmed  requests  (described  in  detail  in  Chapter  9)  are  source 
program  instructions  which  pass  arguments  to  the  monitor  and  request 
monitor  services.  These  instructions  allow  user  assembly  language 
programs  to  utilize  the  available  monitor  features. 


2.1  START  PROCEDURE 

After  the  system  has  been  built  (see  Appendix  A  and  the  GETTING 
STARTED  WITH  RT-11  document,  DEC-11-0RCPA-D-D) ,  the  monitor  can  be 
loaded  into  memory  from  disk  or  DECtape  as  follows : 

1.  Press  HALT. 

2.  Mount  the  system  device  on  unit  0.  Note  that  if  disk  unit  0 
is  disabled,  RT-11  can  be  loaded  from  another  RK  disk  unit 
using  the  software  bootstrap  described  later  in  this  section. 

3.  If  a  disk  is  being  used,  be  sure  the  WRITE  PROTECT  light  is 
lit. 

4.  If  a  DECtape  unit  is  being  used,  set  the  WRITE  ENABLE/WRITE 
LOCK  switch  to  WRITE  LOCK  and  the  REMOTE/OFF/LOCAL  switch  to 
REMOTE. 

If  the  hardware  configuration  includes  the  BM792-YB  hardware 
bootstrap: 

1.  Set  the  Switch  Register  to  173100  (the  address  of  the  ROM 
Bootstrap  Loader) . 
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2.  Press  the  LOAD  ADDR  switch. 

3.  Set  the  Switch  Register  to  the  address  of  the  word  count 
register  of  disk  or  DECtape  on  which  the  monitor  resides: 

177462  for  RF11  disk 

177406  for  RK11,RK05  disk 

177344  for  DECtape 

4.  Press  the  START  switch. 

If  the  hardware  configuration  includes  the  MR11-DB  hardware  bootstrap: 

1.  Set  the  Switch  Register  to: 

773100  for  RF11  disk 

773110  for  RK11,RK05  disk 

773120  for  DECtape 

2.  Press  the  LOAD  ADDR  switch. 

3.  Press  the  START  switch. 

If  neither  hardware  bootstrap  is  available,  or  if  an  RK  disk  unit 
other  than  0  is  to  be  used  as  the  system  device,  one  of  the  following 
bootstraps  must  be  entered  manually  using  the  switch  register.  First 
set  the  switch  register  to  1000  and  press  the  LOAD  ADDR  switch.  Then 
set  the  switch  register  to  the  first  value  shown  for  the  appropriate 

bootstrap  and  raise  the  DEPosit  switch.  Continue  depositing  the 

values  shown. 


Disk 

RK  Disk  (other 

Disk 

DECtape 

(RK11 ,RK05) 

than  Unit  0) 

(RF11) 

12700 

12700 

12700 

12700 

177344 

177406 

177406 

177466 

12710 

12710 

12760 

5010 

177400 

177400 

xxxxxx  * 

5040 

12740 

12740 

4 

12740 

4002 

5 

12700 

177400 

5710 

105710 

177406 

12740 

100376 

100376 

12710 

5 

12710 

5007 

177400 

105710 

3 

12740 

100376 

105710 

5 

5007 

100376 

105710 

12710 

100376 

5 

5007 

105710 

100376 

5007 

*  xxxxxx  =  20000 

for 

unit 

1 

40000 

for 

unit 

2 

60000 

for 

unit 

3 

100000 

for 

unit 

4 

120000 

for 

unit 

5 

140000 

for 

unit 

6 

160000 

for 

unit 

7 
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When  all  the  values  have  been  entered ,  set  the  switches  to  1000  and 
press  the  LOAD  ADDR  and  START  switches. 

The  monitor  loads  into  memory  and  prints  one  of  the  following 
identification  messages  followed  by  a  dot  (•)  on  the  terminal: 

RT-11SJ  VO 2- 01 
RT-11FB  V02-01 

The  message  printed  indicates  which  monitor  (Single-Job  or  F/B)  has 
been  loaded;  the  user  may  determine  which  is  to  be  loaded  during  the 
system  build  operation.  Refer  to  the  building  instructions  in 
Appendix  A  or  the  GETTING  STARTED  WITH  RT-11  document  for 
instructions  on  how  to  initialize  the  system  for  either  monitor  and 
for  directions  on  how  to  bring  up  the  alternate  monitor  while  under 
control  of  the  one  currently  running. 

After  the  message  has  printed ,  the  system  device  should  be  WRITE 
ENABLED.  The  monitor  is  ready  to  accept  keyboard  commands. 


2.2  SYSTEM  CONVENTIONS 

Special  character  commands ,  file  naming  procedures  and  other 
conventions  that  are  standard  for  the  RT-11  system  are  described  in 
this  section.  The  user  should  be  familiar  with  these  conventions 
before  running  the  system. 


2.2.1  Data  Formats 

The  RT-11  system  makes  use  of  five  types  of  data  formats:  ASCII , 
object ,  memory  image ,  relocatable  image ,  and  load  image. 

Files  in  ASCII  format  conform  to  the  American  National  Standard  Code 
for  Information  Interchange ,  in  which  each  character  is  represented  by 
a  7-bit  code.  Files  in  ASCII  format  include  program  source  files 
created  by  the  Editor ,  listing  and  map  files  created  by  various  system 
programs ,  and  data  files  consisting  of  alphanumeric  characters.  A 
chart  containing  ASCII  character  codes  appears  in  Appendix  C. 

Files  in  object  format  consist  of  data  and  PDP-11  machine  language 
code.  Object  files  are  those  output  by  the  assembler  or  FORTRAN 
compiler  and  are  used  as  input  to  the  Linker. 

The  Linker  can  output  files  in  memory  image  format  (,SAV)#  relocatable 
image  format  (.REL),  or  load  image  format  ( . LDA) . 

A  memory  image  file  (.SAV)  is  a  1  picture1  of  what  memory  will  look 
like  when  a  program  is  loaded.  The  file  itself  requires  the  same 
number  of  disk  blocks  as  the  corresponding  number  of  256-word  memory 
blocks. 

A  relocatable  image  file  (.REL)  is  one  which  can  be  run  in  the 
foreground.  It  differs  from  a  memory  image  file  in  that  the  file  is 
linked  as  though  its  bottom  address  were  0.  When  the  program  is  called 
(using  the  monitor  FRUN  command) ,  the  file  is  relocated  as  it  is 
loaded  into  memory.  (A  memory  image  file  requires  no  such 
relocation. ) 
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A  load  image  (or  .LDA)  file  may  be  produced  for  compatibility  with  the 
PDP-11  Paper  Tape  System  and  is  loaded  by  the  absolute  binary  loader, 
LDA  files  can  be  loaded  and  executed  in  stand-alone  environments 
without  relocation. 


2,2.2  Prompting  Characters 

The  following  table  summarizes  the  characters  typed  by  RT-11  to 
indicate  to  the  user  either  that  the  system  is  awaiting  user  response 
or  to  specify  which  job  (foreground  or  background)  is  producing 
output  s 


Table  2-1 

Prompting  Characters 


Character 


Meaning 


The  Keyboard  Monitor  is  waiting  for  a  command  (see 
Section  2,3,2), 

The  Command  String  Interpreter  is  waiting  for  a 
command  string  specification  as  explained  in 
Sections  2.3,3  and  2.5. 

When  the  console  terminal  is  being  used  as  an 
input  file,  the  uparrow  prompts  the  user  to  enter 
information  from  the  keyboard.  If  the  input  is 
entered  under  EDIT  or  BASIC  (or  any  program  that 
accepts  input  in  special  terminal  mode  as 
described  in  Chapter  9) ,  the  characters  entered 
are  not  echoed.  Typing  a  CTRL  Z  marks  the 
end-of-file. 

The  >  character  is  used  (under  the  F/B  Monitor  and 
only  if  a  foreground  job  is  active)  to  identify 
which  job,  foreground  or  background,  is  producing 
the  output  currently  appearing  on  the  console 
terminal.  Each  time  output  from  the  background 
job  is  to  appear,  B>  is  printed  first,  followed  by 
the  output.  If  the  foreground  job  is  to  print 
output,  F>  is  typed  first.  B>  and  F>  are  also 
printed  as  a  result  of  the  CTRL  B  and  CTRL  F 
commands  described  in  Table  2-4. 


2.2.3  Physical  Device  Names 

Devices  are  referenced  by  means  of  a  standard  two-character  device 
name.  Table  2-2  lists  each  name  and  its  related  device.  If  no  unit 
number  is  specified  for  devices  which  have  more  than  one  unit,  unit  0 
is  assumed. 
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Table  2-2 

Permanent  Device  Names 

Permanent  Name 

I/O  Device 

CR: 

Card  Reader  (CR11/CM11) . 

CTns 

TA11  cassette  (n  is  the  unit  number,  0  or  1) 

DK: 

The  default  storage  device  for  all  files.  DK  is 
initially  the  same  as  SY:  (see  below),  but  the 
assignment  can  be  changed  with  the  ASSIGN  Command 
(Section  2. 7. 2. 4.) 

DTn: 

DEC tape  n,  where  n  is  a  unit  number  (an  integer  in 
the  range  0  to  7,  inclusive). 

LPs 

Line  printer. 

MTns 

Industry  compatible  magtape  (n  is  an  integer 
between  0  and  7,  inclusive). 

PP: 

High-speed  paper  tape  punch. 

PR: 

High-speed  paper  tape  reader. 

RF: 

RF11  fixed-head  disk  drive. 

RKn: 

RK  disk  cartridge  drive  n  (n  is  in  the  range  0  to 

7  inclusive) . 

SY: 

System  device;  the  device  and  unit  from  which  the 
system  is  bootstrapped.  (RT-11  allows 
bootstrapping  from  any  RK  unit;  refer  to  Section 
2.1.) 

SYn: 

The  specified  unit  of  the  same  device  type  as  that 
from  which  the  system  was  bootstrapped. 

TT: 

Terminal  keyboard  and  printer. 

In  addition  to  the  fixed  names  shown  in  Table  2-2 ,  devices  can  be 
assigned  logical  names.  A  logical  name  takes  precedence  over  a 
physical  name  and  thus  provides  device  independence.  With  this 
feature  a  program  that  is  coded  to  use  a  specific  device  does  not  need 
to  be  rewritten  if  the  device  is  unavailable.  Refer  to  Section 

2. 7. 2. 4  for  instructions  on  assigning  logical  names  to  devices. 

2.2.4  File  Names  and  Extensions 

Files  are  referenced  symbolically  by  a  name  of  one  to  six  alphanumeric 
characters  followed,  optionally,  by  a  period  and  an  extension  of  up  to 
three  alphanumeric  characters.  (Excess  characters  in  a  filename  may 
cause  an  error  message.)  The  extension  to  a  filename  generally 
indicates  the  format  of  a  file.  It  is  a  good  practice  to  conform  to 
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the  standard  filename  extensions  for  RT-11.  If  an  extension  is  not 
specified  for  an  input  or  output  file,  most  system  programs  assign 
appropriate  default  extensions*  Table  2-3  lists  the  standard 
extensions  used  in  RT-11. 


Table  2-3 

File  Name  Extensions 

Extension 

Meaning 

•  BAD 

Files  with  bad  (unreadable)  blocks;  this 
extension  can  be  assigned  by  the  user 
whenever  bad  areas  occur  on  a  device.  The 
.BAD  extension  makes  the  file  permanent  in 
that  area,  preventing  other  files  from  using 
it  and  consequently  becoming  unreadable. 

•  BAK 

Editor  backup  file. 

.BAS 

BASIC  source  file  (BASIC  input) . 

.DAT 

BASIC  or  FORTRAN  data  file. 

.DMP 

DUMP  output  file. 

.FOR 

FORTRAN  IV  source  file  (FORTRAN  input) . 

•  LDA 

Absolute  binary  file  (optional  Linker 

output) • 

•  LLD 

Library  listing  file. 

•  LST 

Listing  file  (MACRO  or  FORTRAN  output) . 

.MAC 

MACRO  or  EXPAND  source  file  (MACRO,  EXPAND, 
SRCCOM  input) . 

.MAP 

Map  file  (Linker  output) . 

.OBJ 

Relocatable  binary  file  (MACRO,  ASEMBL, 
FORTRAN  IV  output.  Linker  input,  LIBR  input 
and  output) . 

.PAL 

Output  file  of  EXPAND  (the  MACRO  expander 
program) ,  input  file  of  ASEMBL. 

.REL 

Foreground  job  relocatable  image  (Linker 

output,  default  for  monitor  FRUN  command) . 

.SAV 

Memory  image  or  SAVE  file;  default  for  R, 
RUN,  SAVE  and  GET  Keyboard  Monitor  commands; 
also  default  for  output  of  Linker. 

.SYS 

System  files  and  handlers. 
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If  a  filename  with  a  blank  extension  is  to  be  used  in  a  command  line 
in  which  a  default  extension  is  assumed  (by  either  the  monitor  or  a 
system  program) ,  the  user  must  insert  a  period  after  the  filename  to 
indicate  that  there  is  no  extension.  For  example,  to  run  the  file 
TEST,  type  s 

RUN  TEST. 

If  the  period  after  the  filename  is  not  given,  the  monitor  assumes  the 
.SAV  extension  and  attempts  to  run  a  file  named  TEST.SAV. 


2.3  MONITOR  SOFTWARE  COMPONENTS 
The  main  RT-11  monitor  software  components  ares 
Resident  Monitor  (RMON) 

Keyboard  Monitor  (KMON) 

User  Service  Routine  (USR)  and  Command  String  Interpreter  (CSI) 
Device  Handlers 

The  reader  may  find  Figure  2-1  helpful  while  reading  the  following 
descriptions . 


2.3.1  Resident  Monitor  (RMON) 

The  Resident  Monitor  is  the  only  permanently  memory-resident  part  of 
RT-11.  The  programmed  requests  for  all  services  of  RT-11  are  handled 
by  RMON.  RMON  also  contains  the  console  terminal  service,  error 
processor,  system  device  handler,  EMT  processor,  and  system  tables. 


2.3.2  Keyboard  Monitor  (KMON) 

The  Keyboard  Monitor  provides  communication  between  the  user  at  the 
console  and  the  RT-11  system.  Monitor  commands  allow  the  user  to 
assign  logical  names  to  devices,  run  programs,  load  device  handlers, 
and  control  F/B  operations.  A  dot  at  the  left  margin  of  the  console 
terminal  page  indicates  that  the  Keyboard  Monitor  is  in  memory  and  is 
waiting  for  a  user  command. 


2.3.3  User  Service  Routine  (USR) 

The  User  Service  Routine  provides  support  for  the  RT-11  file 
structure.  It  loads  device  handlers,  opens  files  for  read  or  write 
operations,  deletes  and  renames  files,  and  creates  new  files.  The 
Command  String  Interpreter  (the  use  of  which  is  described  in  Section 
2.5)  is  part  of  the  USR  and  can  be  accessed  by  any  program  to 
interpret  device  and  file  I/O  information. 
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2.3,4  Device  Handlers 

Device  handlers  for  the  RT— 11  system  perform  the  actual  transfer  of 
data  to  and  from  peripheral  devices.  New  handlers  can  be  added  to  the 
system  as  files  on  the  system  device  and  can  be  interfaced  to  the 
system  by  modifying  a  few  monitor  tables  (see  the  RT-11  SOFTWARE 
SUPPORT  MANUAL,  DEC-11-0RPGA-B-D  for  instructions  on  how  to  interface 
a  new  handler  to  the  RT-11  monitor) . 


2.4  GENERAL  MEMORY  LAYOUT 

When  the  RT-11  System  is  first  bootstrapped  from  the  system  device, 
memory  is  arranged  as  shown  in  the  left  diagram  of  Figure  2-1  (this  is 
the  case  for  either  the  Single- Job  or  Foreground/Background  Monitor , 
since  no  foreground  job  exists  yet) •  The  background  job  is  the  RT-11 
module  KMON. 

When  an  RT-11  foreground  job  is  initiated  (via  the  monitor  FRUN 
command ,  Section  2. 7. 5.1)  ,  room  is  created  for  the  foreground  job  to 
be  loaded  by  decreasing  the  amount  of  space  available  to  the 
background  job.  The  memory  maps  in  Figure  2-1  illustrate  the  system 
layout  before  and  after  a  foreground  job  is  loaded.  (Refer  also  to 
Chapter  6,  Section  6.5.) 
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KMON 
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KMON 
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AFTER 

LOADING 

THE 
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Figure  2-1 

RT-11  System  Memory  Maps 

As  shown  in  the  figures ,  the  process  of  loading  a  foreground  job 
requires  that  the  USR  and  KMON  be  physically  moved.  Once  a  foreground 
job  is  running ,  it  is  possible  to  communicate  with  either  the 
background  or  foreground  job  via  special  commands  (described  in 
Section  2.7).  All  of  the  terminal  support  functions  described  in 
Section  2.6  are  available  under  both  the  Single- job  and  F/B  Monitors. 

In  addition  to  FRUN,  other  monitor  commands  can  alter  the  memory  map; 
these  are  LOAD,  UNLOAD,  GT  ON,  and  GT  OFF.  LOAD  causes  device 
handlers  to  be  made  resident  until  an  UNLOAD  command  is  performed. 
UNLOAD  deletes  handlers  which  have  been  loaded.  GT  ON  and  GT  OFF 
cause  terminal  service  to  utilize  the  VT-11  display  hardware.  Figure 
2-2  illustrates  the  placement  of  display  modules  and  device  handlers 
in  memory  following  the  GT  ON ,  LOAD ,  and  FRUN  commands : 
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HIGH 

ADDRESSES 


Figure  2-2 

RT-11  Memory  Map  (GT40) 

RT-11  maintains  a  free  memory  list  to  manage  memory.  Thus,  when  a 
handler  is  unloaded,  the  space  the  handler  occupied  is  returned  to  the 
free  memory  list  and  is  reclaimed  by  the  background. 


2.4.1  Component  Sizes 

Following  are  the  approximate  sizes  (in  words)  of  the  components  for 
RT-11,  Version  2. 


F/B 


Single- job 


RMON 

USR 

KMON 


3400(10) 
2050 (10) 
1550(10) 


1650(10) 

2050(10) 

1550(10) 


In  the  F/B  system,  the  background  area  must  always  be  large  enough  to 
hold  KMON  and  USR  (3.5K  words).  The  following  list  indicates  the  total 
space  available  for  the  loaded  device  handlers,  the  foreground  job, 
and  the  display  handler.  Note  that  the  low  memory  area  from  0-477  is 
never  used  for  executable  programs.  (These  sizes  also  allow  room  for 
the  3.5K  RMON) . 

Machine  size  (words)  Space  available  (words) 


16K 

9K 

24K 

17K 

28K 

2  IK 

With  the  Single-Job  Monitor,  RMON  requires  only  1.65K.  The  following 
list  shows  the  amount  of  space  available  to  users  with  the  Single-Job 
Monitor : 
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Machine  size  (words)  Program  space  available  (words) 


8K 

6.35K 

16K 

14.35K 

24K 

22.35K 

28K 

26.35K 

2.5  ENTERING  I/O  INFORMATION 


Once  either  monitor  has  been  loaded  and  a  system  program  (or  any 
program  which  uses  the  Command  String  Interpreter)  has  been  started , 
the  Command  String  Interpreter  prints  an  asterisk  at  the  left  margin. 
In  response  to  the  asterisk,  a  command  string  should  be  entered 
providing  information  about  devices,  filenames  and  extensions,  and 
switch  options.  The  general  format  of  this  command  line  is: 


*OUTPUT=INPUT/SWITCH 


The  =  sign  is  a  delimiter  which  separates  the  output  and  input  fields; 
the  <  sign  may  be  used  in  place  of  the  ■  sign.  See  the  NOTE  at  the 
end  of  this  section. 


OUTPUT  is  entered  in  the  format: 

dev:filnam.ext [n] ,. . .dev:filnam.ext [n] 


INPUT  as: 


dev:filnam.ext,. . .dev:filnam.ext 


and  SWITCH  as: 

/s:oval  or  /sldval 

where : 


dev: 


filnam.ext 


[n] 


/s:oval  or 
/sidval 


in  each  case  is  an  optional  two  to  three-character 
name  from  Table  2-2  whose  usage  conforms  to  the 
NOTE  below. 

in  each  case  is  the  name  of  a  file  (consisting  of 
one  to  six  alphanumeric  characters  followed 
optionally  by  a  dot  and  a  zero  to  three-character 
extension) .  As  many  as  three  output  and  six  input 
files  may  be  allowed. 

is  an  optional  declaration  of  the  number  of  blocks 
(n)  desired  for  an  output  file,  n  is  a  decimal 
number  (<2(16)-1)  enclosed  in  square  brackets 
immediately  following  the  output  filnam.ext  to 
which  it  applies. 

is  one  or  more  optional  switches  whose  functions 
vary  according  to  the  program  in  use  (refer  to  the 
switch  option  table  in  the  appropriate  chapter) . 
oval  is  either  an  octal  number  or  one  to  three 
alphanumeric  characters  (the  first  of  which  must 
be  alphabetic)  which  will  be  converted  to  radix- 50 
(see  Section  5.5.4  of  the  MACRO  chapter),  dval  is 
a  decimal  value  preceded  by  an  exclamation  point. 
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Throughout  this  manual ,  the  /ssoval  construction 
is  used;  however,  the  /sldval  format  is  always 
valid.  Generally,  these  switches  and  their 
associated  values,  if  any,  should  follow  the 
device  and  filename  to  which  they  apply. 

If  the  same  switch  is  to  be  repeated  several  times 
with  different  values  (e.g.,  /L : MEB/L : TTM/L : CND  to 
MACRO)  the  line  may  be  abbreviated  as 
/L:MEB:TTM:CND;  octal,  RAD50,  and  decimal  values 
may  be  mixed. 


NOTE 

As  illustrated  in  the  general  format  of 
a  command  line,  the  command  line 
consists  of  an  output  list,  a  separator 
(“  or  <) ,  and  an  input  list.  The 
separator  can  be  omitted  if  there  are  no 
output  files.  Omission  of  a  device 
specification  in  either  the  input  or 
output  list  is  handled  as  follows: 

DK:  is  assumed  if  the  first  file  in  a 

list  has  no  explicit  device.  OK  (or  the 
device  associated  with  the  first  file) 
is  default  until  another  device  is 
indicated;  that  device  then  becomes 
default  until  a  new  one  is  used,  and  so 
on.  If  the  following  command  is 
entered,  for  example,  to  MACRO: 

*DT1.  FIRST.  OBJ,  LP:=TASK.  1,  RK1 :  TASK.  2,  TASK.  2 

it  is  interpreted  as  though  all  devices 
had  been  indicated  as  follows: 

*DT1 .  FIRST.  OBJ,  LP  :  =  DK  :  TASK.  1,  RK1 :  TASK.  2,  RK1 :  TASK.  2 


2.6  KEYBOARD  COMMUNICATION  (KMON) 

Special  function  keys  and  keyboard  commands  allow  the  user  to 
communicate  with  the  RT— 11  monitor  and  allow  him  to  allocate  system 
resources,  manipulate  memory  images,  start  programs,  and  use 
foreground/background  services. 

The  special  functions  of  certain  terminal  keys  used  for  communication 
with  the  Keyboard  Monitor  are  explained  in  Table  2-4.  Note  that  in  the 
F/B  system,  the  Keyboard  Monitor  always  runs  as  a  background  job. 

CTRL  commands  are  entered  by  holding  the  CTRL  key  down  while  typing 
the  appropriate  letter. 


2-11 


System  Communication 


Table  2-4 

Special  Function  Keys 

Key 

Function 

CTRL  A 

Valid  when  the  monitor  GT  ON  command  has  been  typed  and 
the  display  is  in  use.  The  command  does  not  echo  on 
the  terminal.  It  is  used  after  a  CTRL  S  has  been  typed 
to  effectively  page  output.  Console  output  is 
permitted  to  resume  until  the  screen  is  completely 
filled;  text  previously  displayed  is  scrolled  upward 
off  the  screen.  CTRL  A  has  no  special  meaning  if  GT  ON 
is  not  in  effect  or  if  a  SET  TTY  NOPAGE  command  has 
been  given  (see  Section  2. 7. 2. 8). 

CTRL  B 

Under  the  F/B  Monitor  echoes  B>  on  the  terminal  (unless 
output  is  already  coming  from  the  background  job)  and 
causes  all  keyboard  input  to  be  directed  to  the 
background  job.  At  least  one  line  of  output  will  be 
taken  from  the  background  job  (the  foreground  job  has 
priority,  and  control  will  revert  to  it  if  it  has 
output) .  All  typed  input  will  be  directed  to  the 
background  job  until  control  is  redirected  to  the 
foreground  job  (via  CTRL  F) .  CTRL  B  has  no  special 
meaning  when  used  under  a  Single-Job  Monitor  or  when  a 
SET  TTY  NOFB  command  has  been  issued  (see  Section 

2. 7. 2. 8). 

CTRL  C 

Echoes  tC  on  the  terminal,  interrupts  current  program 
execution,  and  returns  control  to  the  Keyboard  Monitor. 
Note  that  under  the  F/B  Monitor,  the  job  which  is 
currently  receiving  input  will  be  the  job  that  is 
stopped  (determined  by  whether  a  CTRL  F  or  CTRL  B  was 
most  recently  typed) .  To  ensure  that  the  command  is 
directed  to  the  proper  job,  type  CTRL  B  or  CTRL  F 
before  typing  CTRL  C.  If  a  program  is  waiting  for 
terminal  input  or  is  using  the  device  handler  TT  for 
input,  typing  a  single  CTRL  C  interrupts  execution  and 
returns  control  to  the  monitor  command  level; 
otherwise,  two  CTRL  C's  must  be  typed  in  order  to 
interrupt  execution. 

CTRL  E 

Valid  when  the  monitor  GT  ON  command  has  been  typed  and 
the  display  is  in  use.  The  command  does  not  echo  on 
the  terminal,  but  causes  all  terminal  output  to  appear 
on  both  the  display  screen  and  the  console  terminal 
simultaneously.  A  second  CTRL  E  disables  console 
terminal  output.  CTRL  E  has  no  special  meaning  if 
GT  ON  is  not  in  effect. 

CTRL  F 

Under  the  F/B  Monitor  echoes  F>  on  the  terminal  and 
instructs  that  all  keyboard  input  be  directed  to  the 
foreground  job  and  all  output  be  taken  from  the 
foreground  job.  If  no  foreground  job  exists,  F?  is 
printed  and  control  is  directed  to  the  background  job. 
Otherwise,  control  remains  with  the  foreground  job 
until  redirected  to  the  background  job  (via  CTRL  B)  or 
until  the  foreground  job  terminates.  CTRL  F  has  no 
special  meaning  when  used  under  a  Single- Job  Monitor, 
or  when  a  SET  TTY  NOFB  command  has  been  used  (see 
Section  2. 7. 2. 8). 
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Table  2-4  (Cont.) 
Special  Function  Keys 


Key 

Function 

CTRL  0 

Echoes  to  on  the  terminal  and  causes  suppression  of 
teleprinter  output  while  continuing  program  execution. 
Teleprinter  output  is  re-enabled  when  one  of  the 
following  occurs; 

1.  A  second  CTRL  0  is  typed . 

2.  A  return  to  the  monitor  occurs,  or 

3.  The  running  program  issues  a  . RCTRLO 

directive  (see  Chapter  9) .  (RT-11  system 

programs  reset  CTRL  0  to  the  echoing  state 
each  time  a  new  command  string  is  entered.) 

CTRL  Q 

Does  not  echo.  Resumes  printing  characters  on  the 
terminal  from  the  point  at  which  printing  was 
previously  stopped  (via  CTRL  S) .  CTRL  Q  has  no  special 
meaning  if  a  SET  TTY  NOPAGE  command  has  been  used  (see 
Section  2. 7. 2. 8). 

CTRL  S 

Does  not  echo.  Temporarily  suspends  output  to  the 
terminal  until  a  CTRL  Q  is  typed.  If  GT  ON  is  in 
effect,  each  subsequent  CTRL  A  causes  output  to  proceed 
until  the  screen  has  been  refilled  once.  This  feature 
allows  users  with  high-speed  terminals  to  fill  the 
display  screen,  stop  output  with  CTRL  S,  read  the 
screen,  and  then  continue  with  CTRL  Q  or  CTRL  A. 
(Typing  CTRL  C  in  this  case  also  continues  output.) 
Under  the  F/B  Monitor,  CTRL  S  has  no  special  meaning  if 
a  SET  TTY  NOPAGE  has  been  used. 

CTRL  U 

Deletes  the  current  input  line  and  echoes  as  tU 
followed  by  a  carriage  return  at  the  terminal.  (The 
current  line  is  defined  to  be  all  characters  back  to, 
but  not  including,  the  most  recent  line  feed,  CTRL  C  or 
CTRL  Z.) 

CTRL  Z 

Echoes  tz  on  the  terminal  and  terminates  input  when 
used  with  the  terminal  device  handler  (TT) .  The  CTRL  Z 
itself  does  not  appear  in  the  input  buffer.  If  TT  is 
not  being  used,  CTRL  Z  has  no  special  meaning. 

RUBOUT 

Deletes  the  last  character  from  the  current  line  and 
echoes  a  backslash  plus  the  character  deleted.  Each 
succeeding  RUBOUT  deletes  and  echoes  another  character. 

An  enclosing  backslash  is  printed  when  a  key  other  them 
RUBOUT  is  typed.  This  erasure  is  done  right  to  left  up 
to  the  beginning  of  the  current  line. 

2.6.1  Foreground/Background  Terminal  I/O 

It  is  important  to  note  that  console  input  and  output  under  F/B  are 
independent  functions;  input  can  be  typed  to  one  job  while  output  is 
printed  by  another.  The  user  may  be  in  the  process  of  typing  input  to 
one  job  when  the  other  job  is  ready  to  print  on  the  terminal ,  in  which 
case  the  job  which  has  output  interrupts  the  user  and  prints  the 
output  on  the  terminal;  input  control  is  not  redirected  to  this  job, 
however,  unless  a  CTRL  B  or  CTRL  F  is  explicitly  typed.  If  input  is 
typed  to  one  job  while  the  other  has  output  control,  echo  of  the  input 
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is  suppressed  until  the  job  accepting  input  gains  output  control;  at 
this  point  all  accumulated  input  is  echoed* 

If  the  foreground  job  and  background  job  are  both  ready  to  print 
output  at  the  same  time,  the  foreground  job  has  priority.  Output  from 
the  foreground  job  prints  until  a  line  feed  is  encountered ,  at  which 
point  output  from  the  background  job  prints  until  a  line  feed  is 
encountered ,  and  so  forth. 

When  the  foreground  job  terminates ,  control  reverts  automatically  to 
the  background  job. 


2.6.2  Type- Ahead 

The  monitor  has  a  type-ahead  feature  which  allows  terminal  input  to  be 
entered  while  a  program  is  executing.  For  example: 

.  R  PIP 

*DTl:TflPE=PR: 

DTI :/L 
*13-FEB-74 

TAPE  78  12-FEB-74 

486  FREE  BLOCKS 

While  the  first  command  line  is  executing ,  the  second  line  (DT1:/L)  is 
entered  by  the  user.  This  terminal  input  is  stored  in  a  buffer  and 
used  when  the  first  operation  has  completed. 

If  a  single  CTRL  C  is  typed  while  in  this  mode,  it  is  put  into  the 
buffer.  The  program  currently  executing  exits  when  a  terminal  input 
request  needs  to  be  satisfied.  A  double  CTRL  C  returns  control  to  the 
monitor  immediately. 

If  type-ahead  input  exceeds  80  characters,  the  terminal  bell  rings  and 
no  characters  are  accepted  until  part  of  the  type-ahead  buffer  is  used 
by  a  program  or  characters  are  deleted.  No  input  is  lost.  Type-ahead 
is  particularly  useful  in  specifying  multiple  command  lines  to  system 
programs,  as  shown  in  the  preceding  example.  If  a  job  is  terminated 
by  typing  two  CTRL  C*s,  any  unprocessed  type-ahead  is  discarded. 


NOTE 

If  type-ahead  is  used  in  conjunction 
with  EDIT  or  BASIC,  there  is  no  terminal 
echo  of  the  characters  but  they  are 
stored  in  the  buffer  until  a  new  command 
is  needed.  The  characters  are  echoed 
only  when  actually  used  by  the  program. 


2.7  KEYBOARD  COMMANDS 

Keyboard  commands  allow  the  user  to  communicate  with  the  monitor. 
Keyboard  commands  can  be  abbreviated;  optional  characters  in  a 
command  are  delimited  (in  this  section  only)  by  braces.  Keyboard 
commands  require  at  least  one  space  between  the  command  and  the  first 
argument.  All  command  lines  are  terminated  by  a  carriage  return. 
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All  commands,  with  the  exception  of  those  described  in  Section  2.7.5, 
may  be  used  under  either  the  Single-Job  or  P/B  Monitor.  The  commands 
described  in  Section  2.7.5  apply  only  to  the  F/B  Monitor. 


NOTE 

Any  reference  made  to  "the  background 
job"  applies  as  well  to  the  Single-Job 
Monitor,  since  the  background  job  in  a 
F/B  system  is  equivalent  to  the 
single- job  environment  in  its  normal 
state. 


2.7.1  Commands  to  Control  Terminal  I/O  (GT  ON  and  GT  OFF) 


GT  ON/GT  OFF 


The  GT  ON  and  GT  OFF  commands  are  used  to  enable  and  disable  the 
scroller  (VT-11  display  hardware) .  GT  ON  causes  the  display  screen  to 
replace  the  console  as  the  terminal  output  device.  Switch  options 
allow  the  user  to  control  the  number  of  lines  to  appear  on  the  screen 
and  to  position  the  first  line  vertically.  Output  appears  on  the 
display  in  the  same  format  as  it  would  on  the  console  (i.e.,  output, 
text,  and  commands  are  displayed  in  the  order  in  which  they  occur) • 
GT  ON  is  not  permitted  in  an  8K  configuration. 

The  form  of  the  GT  ON  command  is: 

GT  ONj/L:nJ|/T:nJ 

where : 

/L;n  represents  an  optional  switch  setting  indicating  the 

number  of  lines  of  text  to  display;  the  suggested 
range  is: 

12"  screen  l<=n<=37  octal  (31  decimal) 

(GT40 ,  DEClab) 

17"  screen  l<=n<*50  octal  (40 

(GT44)  decimal) 


/T:n  represents  an  optional  switch  setting  indicating  the 

top  position  of  the  scroll  display;  the  suggested 
range  is: 

12"  screen  l<=*n<*1300  octal  (744  decimal) 

(GT40 ,  DEClab) 
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17"  screen  l<=n<*1750  octal  (1000 

(GT44)  decimal) 

If  no  switches  are  specified,  a  test  for  the  screen  size  is  performed 
and  default  values  are  automatically  assigned  as  follows: 

12"  screen  /L:37  (31  decimal) 

(GT40,  DEClab)  /T:1350  (744  decimal) 

17"  screen  /L:50  (40  decimal) 

(GT44)  /T:1750  (1000  decimal) 

Once  the  display  has  been  activated  with  the  GT  ON  command,  CTRL  A, 
CTRL  S,  CTRL  E  and  CTRL  Q  can  be  used  to  control  scrolling  behavior. 
These  commands  are  described  in  Section  2.6. 

NOTE 

ODT  is  one  exception  to  the  use  of  GT 
ON.  This  system  program  has  its  own 
terminal  handler  and  cannot  make  use  of 
the  display;  output  will  appear  only  on 
the  console  terminal  whenever  ODT  is 
running. 

The  GT  OFF  command  clears  the  display  and  resumes  output  on  the 
teleprinter.  The  command  format  is: 

GT  OFF 

If  GT  ON  and  GT  OFF  are  used  when  no  display  hardware  exists  or  when  a 
foreground  job  is  active,  the  ?ILL  CMD?  message  is  printed. 


2.7.2  Commands  to  Allocate  System  Resources 


DATE 


2. 7. 2.1  DATE  Command  -  The  DATE  command  enters  the  indicated  date  to 
the  system.  This  date  is  then  assigned  to  newly  created  files,  new 
device  directory  entries  (which  may  be  listed  with  PIP) ,  and  listing 
output  until  a  new  DATE  command  is  issued. 

The  form  of  the  command  is: 

DAT | E |  jdd-mmm-yy| 

where  dd-mmm— yy  is  the  day,  month  and  year  to  be  entered.  dd  is  a 
decimal  number  in  the  range  1-31;  mmm  is  the  first  three  characters  of 
the  name  of  the  month,  and  yy  is  a  decimal  number  in  the  range  73-99. 
If  no  argument  is  given,  the  current  date  is  printed. 
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Examples : 

DATE  21-FEB-74  Enter  the  date  21-FEB-74  as  the  current 

system  date. 

DAT  Print  the  current  date. 

21-FEB-74 

If  the  date  is  entered  in  an  incorrect  format,  the  ?DAT?  error 
message  is  printed. 


TIME 


2. 7.2 .2  TIME  Command  -  The  TIME  command  allows  the  user  to  find  out 
the  current  time  of  day  kept  by  RT-11  or  to  enter  a  new  time  of  day. 
If  no  KW11-L  clock  is  present  on  the  system ,  the  ?N0  CLOCK?  error 
message  is  generated.  If  the  time  is  entered  in  an  incorrect  format , 
the  ?TIM?  message  is  printed. 

The  form  of  the  command  iss 

TIm|e|  |hh:mm:ssj- 

where  hhsmmjss  represents  the  hour,  minute,  and  second.  Time  is 
represented  as  hours,  minutes,  and  seconds  past  midnight  in  24-hour 
format  (e.g.,  1:25:00  P.M.  is  entered  as  13:25:00).  If  any  of  the 
arguments  are  omitted,  0  is  assumed.  If  no  argument  is  given,  the 
current  time  of  day  is  output. 

Examples : 


TIM  8:15:23 


Sets  the  time  of  day  to  8  hours,  15 
minutes  and  23  seconds. 


.  TIM 

08 : 25 : 27 


Approximately  10  minutes  later,  the 
TIME  command  outputs  this  time. 


.  TIME  18:5  Sets  the  time  of  day  to  18:05:00. 

The  time  of  day  and  date  are  not  automatically  reset  when  the  time 
reaches  24:00. 
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INITIALIZE 


2. 7. 2. 3  INITIALIZE  Command  -  The  INITIALIZE  command  is  used  to  reset 
several  background  system  tables  and  do  a  general  "clean-up"  of  the 
background  area;  it  has  no  effect  on  the  foreground  job.  In 
particular,  this  command: 

1.  Makes  non-resident  those  handlers  which  were  not  loaded  (via 
LOAD) ,  and 

2.  Purges  the  background's  I/O  channels. 

INITIALIZE  halts  any  I/O  currently  in  progress.  Under  the  Single- Job 
Monitor  a  RESET  instruction  is  done  (see  Chapter  9) .  Under  the  F/B 
Monitor,  I/O  is  stopped  by  entering  each  busy  device  handler  at  a 
special  abort  entry  point. 

The  form  of  the  command  is: 

IN  |lTIALIZE| 

The  INITIALIZE  command  can  be  used  prior  to  running  a  user  program,  or 
when  the  accumulated  results  of  previously  issued  GET  commands  (see 
Section  2,7. 3.1)  are  to  be  discarded . 

Example : 

IN  Initializes  system  background  job 


ASSIGN 


2 • 7 • 2 • 4  ASSIGN  Command  -  The  ASSIGN  command  assigns  a  user-defined 
(logical)  name  as  an  alternate  name  for  a  physical  device.  This  is 
especially  useful  when  a  program  refers  to  a  device  which  is  not 
available  on  a  certain  system.  Using  the  ASSIGN  command,  I/O  can  be 
redirected  to  a  device  which  is  available.  Only  one  logical  name  can 
be  assigned  per  ASSIGN  command,  but  several  ASSIGN  commands  (14 
maximum)  can  be  used  to  assign  different  names  to  the  same  device. 
This  command  is  also  used  to  assign  FORTRAN  logical  units  to  device 
names. 
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The  form  of  the  command  is: 

ASs|lGN|  jdevj  j:udevj 

where : 


dev  is  any  standard  RT-11  (physical)  device  name 

(refer  to  Table  2-1)  with  the  exception  of  DK  and 
SY. 


udev  is  a  1-3  character  alphanumeric  (logical)  name  to 

be  used  in  a  program  to  represent  dev  (if  more 
than  three  characters  are  given,  only  the  first 
three  are  actually  used) . 

:  is  a  delimiter  character  (can  be  a  colon,  equal 

sign,  and,  if  separating  physical  and  logical 
devices,  space). 


The  placement  of  the  delimiter  is  very  important  in  the  ASSIGN 
command;  it  must  be  placed  exactly  as  shown  in  the  following 
examples : 


.  ASSIGN  DTI  INP 


.ASSIGN  DT3.DK 


.ASSIGN  LP=9 


Physical  device  DTI  is  assigned  the 
logical  device  name  INP.  Whenever  a 
reference  to  INP:  is  encountered, 
device  DTI:  is  used. 

Physical  device  name  DT3  is  assigned  the 
default  device  name  DK.  Whenever  DK  is 
referenced  or  defaulted  to,  DT3  is  used. 

FORTRAN  logical  unit  9  becomes  the 
physical  device  name  LP.  All  references 
to  unit  9  use  the  line  printer  for 
output. 


Assignment  of  logical  names  to  logical  names  is  not  allowed. 

If  only  a  logical  device  name  is  indicated  in  the  command  line,  that 
particular  assignment  (only)  is  removed.  Thus: 

ASSIGN  :9  Deassigns  the  logical  name  9  from  its 

physical  device  (LP,  in  the  case  above). 

.  ASSIGN  =DK  Removes  assignment  of  logical  name  DK 

from  its  physical  device  (DT3,  in  the 
case  above) . 

To  remove  all  logical  assignments  for  all  physical  units  of  a  device, 
the  following  command  formats  are  used: 


.  ASSIGN :DT  All  previous  logical  device  assignments 

.  ASSIGN  =DT  for  all  units  of  DECtapes  are  removed. 

If  neither  a  physical  device  name  nor  a  logical  device  name  is 
indicated,  all  assignments  to  all  devices  are  removed. 


ASSIGN 


All  previous  logical  device  assignments 
are  removed. 
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CLOSE 


2. 7. 2. 5  CLOSE  Command  -  The  CLOSE  command  causes  all  currently  open 
output  files  in  the  background  job  to  become  permanent  files.  If  a 
tentative  open  file  is  not  made  permanent,  it  will  eventually  be 
deleted.  The  CLOSE  command  is  most  often  used  after  CTRL  C  has  been 
typed  to  abort  a  background  job  and  to  preserve  any  new  files  that  job 
had  open  prior  to  the  CTRL  Cj  it  has  no  effect  on  a  foreground  job. 

The  form  of  the  command  iss 


The  CLOSE  command  makes  temporary  directory  entries  permanent. 


Example: 


The  Editor  has  a  temporary 
file  open  (TEXT) ,  which  is 
preserved  by  .CLOSE. 


. R  EDIT 
*EWTEXT$$ 

*"C 


. CLOSE 


LOAD 


2. 7. 2. 6  LOAD  Command  -  The  LOAD  command  is  used  to  make  a  device 
handler  resident  for  use  with  background  and  foreground  jobs. 
Execution  is  faster  when  a  handler  is  resident,  although  memory  area 
for  the  handler  must  be  allocated.  Any  device  handler  to  be  used  by  a 
foreground  job  must  be  loaded  before  it  can  be  used. 

The  form  of  the  command  is: 


where : 


represents  any  legal  RT-11  device  name, 
represents  a  delimiter,  denoting  device  ownership, 
represents  the  background  job. 
represents  the  foreground  job. 


dev 


B 


F 


The  dev=F  (and  dev**B)  construction  is  valid  only  under  the 
Foreground/Background  system.  When  used  under  the  Single-Job  Monitor, 
the  ?ILL  DEV?  error  message  occurs. 
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A  device  may  be  owned  exclusively  by  either  the  foreground  or 
background  job.  This  may  be  used,  for  example,  to  prevent  the  I/O  of 
two  different  jobs  from  being  intermixed  on  the  same  non-file 
structured  device.  For  examples 

.LOAD  PP=B r PR r LP-F  The  papertape  punch  belongs  to  the 

background  job  while  the  paper  tape 
reader  is  available  for  use  by 
either  the  background  or  foreground 
job;  the  line  printer  is  owned  by 
the  foreground  job.  All  three 
handlers  are  made  resident  in 
memory. 

Different  units  of  the  same  file-structured  device  may  be  owned  by 
different  jobs.  Thus,  for  example,  DTI  may  belong  to  the  background 
while  DT5  may  belong  to  the  foreground  job.  If  no  ownership  is 
indicated,  the  device  is  available  for  public  use. 

To  change  ownership  of  a  device,  another  LOAD  command  may  be  used;  it 
is  not  necessary  to  first  UNLOAD  the  device.  For  example,  if  RKl  has 
been  assigned  to  the  foreground  job  as  in  the  example  above,  the 
command: 


.LOA  RKl =6 

reassigns  it  to  the  background  job. 

The  system  unit  of  the  system  device  cannot  be  assigned  ownership,  and 
attempts  to  do  so  will  be  ignored.  Other  units  of  the  same  type  as 
the  system  device,  however,  can  be  assigned  ownership. 

LOAD  is  valid  for  use  with  user-assigned  names.  For  example: 

.ASSIGN  RK2 ♦ XY 
.LOA  XY;-F 


If  the  Single- Job,  DECtape-based  Monitor  is  being  used,  loading  the 
necessary  device  handlers  into  memory  can  significantly  improve  the 
throughput  of  the  system,  since  no  handlers  need  to  be  loaded 
dynamically  (in  other  words,  they  need  not  be  loaded,  as  required, 
from  the  DECtape) . 


UNLOAD 


2. 7. 2. 7  UNLOAD  Command  -  The  UNLOAD  command  is  used  to  make  handlers 
that  were  previously  LOADed  non-resident,  freeing  the  memory  they  were 
using. 
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The  form  of  the  command  is: 

UNl|oad}  dev  j, dev,... j 

where : 

dev  represents  any  legal  RT-11  device  name. 

UNLOAD  clears  ownership  for  all  units  of  an  indicated  device  type. 
For  example ,  typing: 

.  UNL  RK2 

clears  all  units  of  RK.  (A  request  to  unload  the  system  device 
handler  clears  ownership  for  any  assigned  units  for  that  device ,  but 
the  handler  remains  resident.) 

Any  memory  freed  is  returned  to  a  free  memory  list  and  eventually 
reclaimed  for  the  background  job  after  the  UNLOAD  command  is  given. 
UNLOAD  is  not  permitted  if  the  foreground  job  is  running.  Such  an 
action  might  cause  a  handler  which  is  needed  by  the  foreground  job  to 
become  non-resident. 

Example : 

.  UNLOAD  LPi PR  The  linepr inter  and  paper  tape 

punch  handlers  are  released  and  the 
area  which  they  used  is  freed. 

A  special  function  of  this  command  is  to  remove  a  terminated 

foreground  job  and  reclaim  memory ,  since  the  space  occupied  by  the 

foreground  job  is  not  automatically  returned  to  the  free  memory  list 

when  it  finishes.  In  this  instance,  the  device  name  FG  is  used  to 

specify  the  foreground  job.  For  example: 

.  UNL  FG 

FG  can  be  mixed  with  other  device  names. 

However,  if,  for  example,  DT2  has  been  assigned  the  name  FG  and  loaded 
into  memory  as  follows: 

♦  ASSIGN  DT2JFG 

♦LOAD  FG 

the  command: 

♦UNLOAD  FG 

causes  the  foreground  job,  not  DT2 ,  to  be  unloaded.  To  unload  DT2, 
this  command  must  be  typed: 


.  UNLOAD  DT2 
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SET 


2, 7, 2, 8  SET  Command  —  The  SET  command  is  used  to  change  device 
handler  characteristics  and  certain  system  configuration  parameters. 

The  form  of  the  command  iss 

SET  dev :  |no |  option=value  |,|Noj>option=value, . . .( 

where :  ’ 


dev:  represents  any  legal  RT-11  physical  device 

name. 

NO  option  is  the  feature  or  characteristic  to  be 

altered. 

=value  is  a  decimal  number  required  in  some  cases. 

A  space  may  be  used  in  place  of  or  in  addition  to  the  colon,  equal 
sign,  or  comma.  Note  that  the  device  indicated  (with  the  exception  of 
TTY)  must  be  a  physical  device  name  and  is  not  affected  by  logical 
device  name  assignments  which  may  be  active.  The  name  of  the 
characteristic  or  feature  to  be  altered  must  be  legal  for  the 
indicated  device  (see  Table  2—5)  and  may  not  be  abbreviated. 

The  SET  command  locates  the  file  SY: DEV. SYS  and  permanently  modifies 
it.  No  modification  is  done  if  the  command  entered  is  not  completely 
valid.  If  a  handler  has  already  been  loaded  when  a  SET  command  is 
issued  for  it,  the  modifications  will  not  take  effect  until  the 
handler  is  unloaded  and  a  fresh  copy  called  in  from  the  system  device. 

Table  2-5  lists  the  system  characteristics  and  parameters  which  may  be 
altered  (those  modes  designated  as  "normal"  are  the  initial  modes) : 


Table  2-5 


SET  Command  Options 


Device  Option 

Alteration 

LP  CR 

Allows  carriage  returns  to  be  sent  to  the 

printer.  For  printers  other  than  the  LS11,  a 
line  feed  performs  all  the  functions  of  a 
carriage  return,  so  ignoring  carriage  returns 
causes  a  significant  increase  in  printing 
speed.  The  CR  option  should  be  used  for  LS11 
line  printers,  and  to  obtain  the  overstriking 
capability  for  any  line  printer.  This  is  the 
normal  mode. 
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Table  2-5  (Cont.) 
SET  Command  Options 


Device 

Option 

Alteration 

LP 

NOCR 

Inhibits  sending  carriage  returns  to  the  line 

printer. 

LP 

FORMO 

Causes  a  form  feed  to  be  issued  before  a 
request  to  print  block  zero.  This  is  the 
normal  mode. 

LP 

NOFORMO 

Turns  off  FORMO  mode. 

LP 

HANG 

Causes  the  handler  to  wait  for  user 
correction  if  the  line  printer  is  not  ready 
or  becomes  not  ready  during  printing.  This 
is  the  normal  mode. 

New  users  should  note  that  when  expecting 
output  from  the  line  printer  and  it  appears 
as  though  the  system  is  not  responding  or  is 
in  an  idle  state,  the  line  printer  should  be 
checked  to  see  if  it  is  on  and  ready  to 
print. 

LP 

NOHANG 

Generates  an  immediate  error  if  the  line 
printer  is  not  ready. 

LP 

LC 

Allows  lower  case  characters  to  be  sent  to 
the  printer.  This  option  should  be  used  if 
the  printer  has  a  lower  case  character  set. 

LP 

NOLC 

Causes  lower  case  characters  to  be  translated 
to  upper  case  before  printing.  This  is  the 
normal  mode. 

LP 

WIDTH=n 

Sets  the  line  printer  width  to  n,  where  n  is 
a  number  between  30  and  255.  Any  characters 
printed  past  column  n  are  ignored.  The  NO 
modifier  is  not  permitted. 

CR 

CODE an 

Modifies  the  card  reader  handler  to  use 
either  the  DEC  026  or  the  DEC  029  card  codes 
(refer  to  Appendix  H) .  n  must  be  either  26  or 
29.  The  NO  modifier  is  not  permitted. 

CR 

CRLF 

Causes  a  carriage  return/line  feed  to  be 
appended  to  each  card  image.  This  is  the 
normal  mode. 

CR 

NOCRLF 

Transfers  each  card  image  without  appending  a 
carriage  return/line  feed. 

CR 

HANG 

Causes  the  handler  to  wait  for  user 
correction  if  the  reader  is  not  ready  at  the 
start  of  a  transfer.  This  is  the  normal 
mode. 

CR 

NOHANG 

Generates  an  immediate  error  if  the  device  is 
not  ready  at  the  start  of  a  transfer.  Note 
that  the  handler  will  wait  regardless  of  how 
the  option  is  set  if  the  reader  becomes  "not 
ready"  during  a  transfer  (i.e.,  the  input 
hopper  is  empty,  but  an  end-of-file  card  has 
not  yet  been  read) . 
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Table  2-5  (Cont.) 
SET  Command  Options 


Device 


Option 


Alteration 


CR 


IMAGE 


Causes  each  card  column  to  be  stored  as 
12-bit  binary  number,  one  column  per  word 
The  CODE  option  has  no  effect  in  IMAGE  mode 
The  format  of  the  12-bit  binary  number  is: 


PDP-11  WORD 


15  14  13  12 

11 

10 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 

UNUSED  (ALWAYS  0) 
- 1 - 1 - 1 - 

ZONE 

ZONE 

ZONE 

ZONE 

ZONE 

ZONE 

ZONE 

ZONE 

ZONE 

ZONE 

ZONE 

ZONE 

12 

11 

0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

This  format  allows  binary  card  images  to  be 
read  and  is  especially  useful  if  a  special 
encoding  of  punch  combinations  is  to  be  used. 
Mark-sense  cards  may  be  read  in  IMAGE  mode. 


CR 


CR 


CR 


NOIMAGE 


TRIM 


NOTRIM 


Allows  the  normal  translation  (as  specified 
by  the  CODE  option)  to  take  place;  data  is 
packed  one  column  per  byte.  Invalid  punch 
combinations  are  translated  into  the  error 
character,  ASCII  "\"  (backslash),  which  is 
octal  code  134.  This  is  the  normal  mode. 

Causes  trailing  blanks  to  be  removed  from 
each  card  read.  It  is  not  recommended  that 
TRIM  and  NOCRLF  be  used  together  since  card 
boundaries  will  be  difficult  to  find.  This 
is  the  normal  mode. 

Transfers  a  full  80  characters  per  card. 


CT 


RAW 


Causes  the  cassette  handler  to  perform  a 
read-after-write  check  for  every  record 
written,  and  retry  if  an  output  error 
occurred.  If  three  retries  fail,  an  output 
error  is  detected. 


CT 


NORAW 


Causes  the  cassette  handler  to  write  every 
record  directly  without  reading  it  back  for 
verification.  This  significantly  increases 
transfer  rates  at  the  risk  of  increased  error 
rates.  Normal  mode  is  NORAW. 


The  following  options,  with  the  exception  of  HOLD  and  NOHOLD,  are 

available  in  the  Foreground/Background  System  only;  HOLD  and  NOHOLD 
are  available  in  both  systems.  These  options  are  not  permanent,  and 
must  be  reissued  whenever  the  monitor  is  re-bootstrapped.  (Note  that 
the  device  specification  is  TTY,  not  TT,  because  the  handler  itself  is 
not  changed.) 


TTY 

CRLF 

Causes  the  monitor  to  issue  a  carriage 
return/line  feed  on  the  console  terminal 
whenever  it  attempts  to  type  past  the  right 
margin  (as  set  by  the  WIDTH  option) •  This  is 
the  normal  mode. 

TTY 

NOCRLF 

Causes  no  special  action  to  be  taken  at  the 
right  margin. 

TTY 

FB 

Causes  the  monitor  to  treat  CTRL  B  and  CTRL  F 
characters  as  background  and  foreground 
program  control  characters  and  does  not 
transmit  them  to  the  user  program.  This  is 
the  normal  mode. 
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Table  2-5  (Cont.) 
SET  Commmand  Options 


Device 

Option 

Alteration 

TTY 

NOFB 

Causes  CTRL  B  and  CTRL  F  to  have  no  special 
meaning, 

NOTE 

SET  TTY  NOFB  is  issued  to  KMON , 

(which  runs  as  a  background  job) 
and  disables  all  communication  with 
the  foreground  job.  To  enable 

communication  with  the  foreground 
job,  issue  the  command  SET  TTY  FB. 

TTY 

FORM 

Indicates  that  the  console  terminal  is 

capable  of  executing  hardware  form  feeds. 

TTY 

NOFORM 

Causes  the  monitor  to  simulate  form  feeds  by 
typing  eight  line  feeds.  This  is  the  normal 
mode. 

TTY 

HOLD 

Enables  use  of  the  hold  screen  mode  of 
operation  for  the  VT50  terminal.  The  command 
is  a  no-op  for  any  terminal  other  them  the 
VT50.  The  command  is  valid  for  F/B  and 
Single- Job  Monitors.  Consult  the  VT50  VIDEO 
TERMINAL  PROGRAMMER'S  MANUAL 
(DEC-OO-OVRSA-A-D)  for  more  information. 

TTY 

NOHOLD 

Disables  use  of  the  hold  screen  mode  of 
operation  for  the  VT50  terminal. 

TTY 

PAGE 

Causes  the  monitor  to  treat  CTRL  S  and  CTRL  Q 
characters  as  terminal  output  hold  and  unhold 
flags,  and  does  not  transmit  them  to  the  user 
program.  This  is  the  normal  mode. 

TTY 

NOPAGE 

Causes  CTRL  S  and  CTRL  Q  to  have  no  special 
meaning. 

TTY 

SCOPE 

Causes  the  monitor  to  echo  RUBOUTs  as 
backspace-space- backspace .  This  mode  should 
be  used  when  the  console  is  a  VT05/VT50  or 
when  GT  ON  is  in  effect. 

TTY 

NOSCOPE 

Causes  the  monitor  to  echo  RUBOUTs  as 
backslash  followed  by  the  character  deleted. 
This  is  the  normal  mode. 

TTY 

TAB 

Indicates  that  the  console  terminal  is 

capable  of  executing  hardware  tabs. 

TTY 

NOTAB 

Causes  the  monitor  to  simulate  tab  stops 
every  eight  positions.  The  normal  mode  is 
NOTAB.  VT05/VT50  terminals  generally  have 
hardware  tabs. 

TTY 

WIDTH =n 

Sets  the  width  of  the  console  terminal  to  n 
positions,  for  the  use  of  the  CRLF  option,  n 
must  be  in  the  range  30-255  (decimal) .  The 
width  is  initially  set  to  72. 
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The  following  variant  of  the  SET  command  is  used  to  prevent  the 
background  job  from  ever  placing  the  USR  in  a  swapping  state  (note 
that  USR  replaces  a  device  specification  in  the  command  line) s 


SET  USR  <N0' 


SWAP 


This  is  useful  when  running  on  a  DEC tape  based  system,  or  when  running 
a  foreground  job  which  requires  the  USR  but  has  no  memory  allocated 
into  which  to  read  it.  When  the  monitor  is  bootstrapped,  it  is  in  the 
SWAP  condition,  i.e.,  the  background  may  place  the  USR  in  a  swapping 
state  via  a  SETTOP. 

The  Single-Job  Monitor  behaves  as  though  the  following  options  are 
sets  NOTAB,  NOFORM,  PAGE,  NOCRLF,  NOSCOPE,  NOHOLD. 


2.7.3  Commands  to  Manipulate  Memory  Images 


GET 


2.7. 3.1  GET  Command  -  The  GET  command  (valid  for  use  with  a 
background  job  only)  loads  the  specified  memory  image  file  (not  ASCII 
or  binary)  into  memory  from  the  indicated  device. 

The  form  of  the  GET  command  is: 


de v : f i lnam . ext 


where : 


dev: 


represents  any  legal  RT-11  device  name.  If  a 
device  is  not  specified,  DK:  is  assumed. 


filnam.ext  represents  a  valid  RT-11  filename  and  extension. 


If  an  extension  is  not  specified,  the  extension 
.SAV  is  assumed. 


The  GET  command  is  typically  used  to  load  a  program  into  memory  for 
modification  and/or  debugging.  The  GET  command  can  also  be  used  in 
conjunction  with  the  Base,  Examine,  Deposit,  and  START  commands  to 
test  patches,  and  can  be  used  with  SAVE  to  make  patches  permanent . 
Multiple  GETs  can  be  used  to  combine  programs •  Thus : 


.  GET  PROG. 


.  GET  ODT.  SfiV 


Loads  ODT  into  memory 

Loads  PROG. SAV  into 
memory  with  ODT 


START  (ODTs  starting  address)  Starts  execution  with  ODT 

(see  Chapter  8) . 
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The  GET  command  cannot  be  used  to  load  overlay  segments  of  programs; 
it  may  only  be  used  to  load  the  root  segment  (that  part  which  will  not 
be  overlaid;  refer  to  Chapter  6,  Linker). 

Multiple  GETS  can  be  used  to  build  a  memory  image  of  several  programs. 
If  identical  locations  are  required  by  any  of  the  programs,  the  later 
programs  overlay  the  previous  ones. 

Examples : 

GET  DT3 : FILE1.  SRV  Loads  the  file  FILEl.SAV  into  memory 

from  DECtape  unit  3. 

GET  NRME1  Loads  the  file  NAME1.SAV  from  device  DK. 


BASE 


2. 7. 3. 2  Base  Command  -  The  B  command  sets  a  relocation  base.  This 
relocation  base  is  added  to  the  address  specified  in  subsequent 
Examine  or  Deposit  commands  to  obtain  the  address  of  the  location  to 
be  referenced.  This  command  is  useful  when  referencing  linked  modules 
with  the  Examine  and  Deposit  commands .  The  base  address  can  be  set  to 
the  address  where  the  module  of  interest  is  loaded.  The  form  of  the 
command  is: 

B  jlocationj 

where : 

location  represents  an  octal  address  used  as  a  base  address  for 
subsequent  Examine  and  Deposit  commands. 

NOTE 

A  space  must  follow  the  B  command 
even  if  an  address  is  not  specified 
(the  B< space >  command  is  equivalent 
to  B  0) . 

Any  non-octal  digit  terminates  an  address.  If  location 
is  odd,  it  is  rounded  down  by  one  to  an  even  address. 

The  base  is  cleared  whenever  user  program  execution  is  initiated. 

Examples : 

B  Sets  base  to  0. 

.  b  260  Sets  base  to  200. 

.  B  201  Sets  base  to  200. 
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EXAMINE 


2. 7. 3. 3  Examine  Command  -  The  E  command  prints  the  contents  of  the 
specified  location (s)  in  octal  on  the  console  terminal.  The  form  of 
the  Examine  command  is: 

E  location  location  m-location  n^ 

where : 

location  represents  an  octal  address  which  is  added  to  the 
relocation  base  value  (the  value  set  by  the  B  Command) 
to  get  the  actual  address  examined.  Any  non-octal 
digit  terminates  an  address.  An  odd  address  is 
truncated  to  become  an  even  address. 

If  more  them  one  location  is  specified  (location  m-location  n) ,  the 
contents  of  location  m  through  location  n  inclusive  are  printed.  The 
second  location  specified  (location  n)  must  not  be  less  them  the  first 
location  specified,  otherwise  an  error  message  is  printed.  If  no 
location  is  specified,  the  contents  of  location  0  are  printed. 
Examination  of  locations  outside  the  background  area  is  illegal. 

Examples : 


.  E  1000  Prints  contents  of  location  1000  (added 

127401  to  the  base  value  if  other  than  0). 

.  E  1001-1012 

127401  007624  127400  000000  000000  000000 

Prints  the  contents  of  locations  1000 
(plus  the  base  value  if  other  them  0) 
through  1013. 


DEPOSIT 


2. 7. 3. 4  Deposit  Command  -  The  Deposit  command  deposits  the  specified 
value (s)  starting  at  the  location  given. 

The  form  of  the  command  is: 

D  location=valuelj,  value 2 , . . . valuen  > 
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where : 


location  represents  an  octal  address  which  is  added  to  the 
relocation  base  value  to  get  the  actual  address  where 
the  values  are  deposited.  Any  non-octal  digit  is 
accepted  as  a  terminator  of  an  address. 

value  represents  the  new  contents  of  the  location. 


If  multiple  values  are  specified  (valuel, . • . ,valuen) ,  they  are 
deposited  beginning  at  the  location  specified.  The  DEPOSIT  command 
accepts  word  or  byte  addresses  but  executes  the  command  as  though  a 
word  address  was  specified.  An  odd  address  is  truncated  by  one  to  an 
even  address.  All  values  are  stored  as  word  quantities. 


Any  character  that  is  not  an  octal  digit  may  be  used  to  separate  the 
locations  and  values  in  a  DEPOSIT  command. 


An  error  results  when  the  address 
outside  the  background  job's  area. 

Examples : 

. D  1000=3705 
.  B  1000 
. D  1500=2502 
.  B  0 


specified  references  a  location 

Deposits  3705  into  location  1000 
Sets  relocation  base  to  1000 
Puts  2503  into  location  2500 
Resets  base  to  0 


SAVE 


2 . 7 . 3 .  S  SAVE  Command  -  The  SAVE  command  writes  specified  user  memory 
areas  to  a  named  file  and  device  in  save  image  formate  Memory  is 
written  from  location  0  to  the  highest  memory  address  specified  by  the 
parameter  list. 

The  SAVE  command  does  not  write  the  overlay  segments  of  programs;  it 
saves  only  the  root  segment  (refer  to  Chapter  6 ,  Linker). 

The  form  of  the  command  is: 

SAvj  E j  dev : f ilnam. ext  ^parameters | 

where : 

dev:  represents  one  of  the  standard  RT-11  block-replaceable 

device  names.  If  no  device  is  specified,  DK  is 
assumed. 


A 
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file. ext  represents  the  name  to  be  assigned  to  the  file  being 

saved.  If  the  file  name  is  omitted,  an  error  message 
is  output.  If  no  extension  is  specified,  the  extension 
.SAV  is  used. 

parameters  represent  memory  locations  to  be  saved.  RT-11 
transfers  memory  in  256-word  blocks.  If  the  locations 
specified  make  a  block  of  less  than  256  words,  enough 
additional  locations  are  transferred  to  make  a  256 -  word 
block. 

Parameters  can  be  specified  in  the  following  format: 
areal , area2-arean 

where : 

areal  represent  an  octal  number  (or  numbers 

area2-arean  separated  by  dashes) .  If  more  than  one  number 

is  specified,  the  second  number  must  be 
greater  than  the  first. 


The  start  address  and  the  Job  Status  Word  are  given  the  default  value 
0  and  the  stack  is  set  to  1000.  If  the  user  wants  to  change  these  or 
any  of  the  following  addresses,  he  must  first  use  the  DEPOSIT  command 
to  alter  them  and  then  SAVE  the  correct  areas: 


Area 


Location 


Start  address  40 
Stack  42 
JSW  44 
USR  address  46 
High  address  50 
Fill  characters  56 


If  the  values  of  the  addresses  are  changed,  it  is  the  user's 
responsibility  to  reset  them  to  their  default  values.  See  Chapter  9 
for  more  information  concerning  these  addresses. 

Examples : 

SAVE  F I  LEI  10008-11000,14000-14100 

Saves  locations  10000(8)  through 
11777(8)  (11000  starts  the  first  word  of 
a  new  block,  therefore  the  whole  block, 
up  to  12000,  is  stored)  and  14000(8) 
through  14777(8)  on  DK  with  the  name 
FILE1.SAV. 

.  SAVE  DTI : NAM. NEW  10000 

Saves  locations  10000  through  10777  on 
DTI:  with  the  name  NAM. NEW. 


.  D  44 .20000 

.  SAV  SV.F'RAM  1000-5777 

Sets  the  reenter  bit  in  the  JSW  and 
saves  locations  1000  through  5777. 
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2.7.4  Commands  to  Start  a  Program 


RUN 


2. 7. 4.1  RUN  Command  -  The  RUN  command  (valid  for  use  with  a 
background  job  only)  loads  the  specified  memory  image  file  into  memory 
and  starts  execution  at  the  start  address  specified  in  location  40. 
Under  the  F/B  system,  10  words  of  user  stack  area  are  required  to 
start  a  user  program,  and  the  stack  address  (location  42)  must  be 
initialized  to  some  part  of  memory  where  these  10  words  will  not 
modify  it. 


The  form  of  the  command  is: 


where : 


devsfilnam.ext 


dev:  is  any  standard  device  name  specifying  a 

block- replaceable  device.  If  dev:  is  not  specified, 
the  device  is  assumed  to  be  DK.  Note  that  devices  MT 
and  CT  are  not  block-replaceable  devices  and 
therefore  cannot  be  used  in  a  RUN  command. 

filnam.ext  is  the  file  to  be  executed.  If  an  extension  is  not 
specified,  the  extension  .SAV  is  assumed. 

The  RUN  command  is  equivalent  to  a  GET  command  followed  by  a  START 
command  (with  no  address  specified) • 

Examples : 


RUN 

DTI :  5RCH.  SflV 

Loads  and  executes  the  file  SRCH.SAV 
from  DTI. 

RUN 

PROG 

Loads  PROG. SAV  from  DK  and  executes  the 
program. 

GET 

PR0G1 

Loads  PROG1.SAV  from  device  DK  without 
executing  it.  Then  combines  PROG1  and 

RUN 

PR0G2 

PROG2.SAV  in  memory  and  begins  execution 
at  the  starting  address  for  PROG2. 
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R 


2. 7. 4. 2  R  Command  -  This  command  (valid  for  use  with  the  background 
job  only)  is  similar  to  the  RUN  command  except  that  the  file  specified 
must  be  on  the  system  device  (SY:). 

The  form  of  the  command  is: 

R  filnam.ext 

No  device  may  be  specified.  If  an  extension  is  not  given,  the 
extension  .SAV  is  assumed. 

Examples : 

.  R  XVZ.  SfiV  Loads  and  executes  XYZ.SAV  from  SY. 

.  R  SRC  Loads  and  executes  SRC. SAV  from  SY. 


START 


2. 7. 4. 3  START  Command  -  The  START  command  begins  execution  of  the 
program  currently  in  memory  (i.e. ,  loaded  via  the  GET  command)  at  the 
specified  address.  START  does  not  clear  or  reset  memory  areas. 

The  form  of  the  command  is: 

ST  |aRT  j>  address 

where : 

address  is  an  octal  number  representing  any  16-bit 
address.  If  the  address  is  omitted,  or  if  0  is 
given,  the  starting  address  in  location  40  will  be 
used. 

If  the  address  given  does  not  exist  or  is  not  an  even  address,  a  trap 
to  location  4  occurs.  In  this  case  a  monitor  error  message  appears. 
If  no  address  is  given,  the  program's  start  address  from  location  40 
is  used. 


2-33 


System  Communication 


Examples : 

' GET  FILE ♦ 1  Loads  FILE.l  into  memory  and  starts  execution 

at  location  100 0. 

♦START  1000 


♦  GET  FI LEA ♦ 
♦GET  FILES* 


Loads  FILEA.SAV,  then  combines  FILEA.SAV  with 
FILEB.SAV  and  starts  execution  at  FILEB  vs 
start  address. 


♦  ST 


REENTER 


2. 7. 4. 4  REENTER  Command  -  The  REENTER  command  starts  the  program  at 
its  reentry  address  (the  start  address  minus  two) .  REENTER  does  not 
clear  or  reset  any  memory  areas  and  is  generally  used  to  avoid 
reloading  the  same  program  for  repetitive  execution.  It  can  be  used 
to  return  to  a  program  whose  execution  was  stopped  with  a  CTRL  C. 

The  form  of  the  command  iss 

re|enter| 

If  the  reenter  bit  (bit  13)  in  the  Job  Status  Word  (location  44)  is 
not  set,  the  REENTER  command  is  illegal. 

For  most  system  programs,  the  REENTER  command  restarts  the  program  at 
the  command  level. 

If  desired,  the  reentry  point  in  a  user  program  can  branch  to  a 
routine  which  initializes  the  tables  and  stack,  fetches  device 
handlers  etc. ,  and  then  continue  normal  operation. 

Example : 

.  R  PIP 
*,'F 

M0NITR.  S  VS 

directory  prints 

•  ( tC  typed) 

. REENTER 

* 


2.7.5  Commands  Used  Only  in  a  Foreground/Background  Environment 

It  is  important  to  note  that  in  order  to  control  execution  of  a 
foreground  job,  the  commands  in  this  section  must  be  typed  to  KMON, 
which  is  running  as  the  background  job.  Thus,  for  example,  to  SUSPEND 


CTRL  C  interrupts  the  PIP 
directory  listing  and  transfers 
control  to  the  monitor  level. 
REENTER  returns  control  to  PIP. 
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the  foreground  job,  the  user 
KMON  as  follows: 

F> 

(tB  typed) 

B> 

R  PIP 
*~C 

SUSPEND 


must  be  sure  he  is  directing  input  to 


Foreground  job  is  running.  Control 
is  redirected  to  the  background  job 
and  PIP  is  called  (the  foreground 
is  still  active) •  CTRL  C  stops  PIP 
and  starts  KMON,  The  foreground 
job  is  suspended,  (See  Section 
2. 7. 5. 2,) 


FRUN 


2. 7. 5.1  FRUN  Command  -  The  FRUN  command  is  used  to  initiate 
foreground  jobs.  FRUN  will  only  run  relocatable  files  produced  with 
the  Linker  /R  switch  (using  the  Linker  supplied  with  RT-11,  Version 
2) .  Any  handlers  used  by  a  foreground  job  must  be  in  memory. 

The  form  of  the  command  is: 

FRu|n|  dev : file. ext j/N:nj j/S:n| j/P | 

where : 

dev:  represents  a  block  replaceable  RT-11  device.  If 

dev:  is  not  specified,  DK:  is  assumed. 

file. ext  represents  the  job  to  be  executed.  The  default 

extension  for  a  foreground  job  is  .REL. 

/N:n  or  /Nln  represents  an  optional  switch  used  to  allocate  n 
words  (not  bytes)  over  and  above  the  actual 
program  size.  (If  running  a  FORTRAN  program,  a 
special  formula  is  used  to  determine  n.  Refer  to 
Appendix  G  for  this  information.) 


/S:n  or  /Sin  represents  an  optional  switch  used  to  allocate  n 
words  (not  bytes)  for  stack  space.  Normally, 
stack  space  is  set  by  default  to  128  words  and  is 
placed  in  memory  below  the  program.  To  change  the 
stack  size,  use  /S:n;  the  stack  is  still  placed  in 
memory  under  the  program.  To  relocate  the  stack 
area,  use  an  .ASECT  (see  Chapter  5)  to  define  the 
start  of  the  user  stack  in  location  42.  This 
overrides  the  /S  switch. 


/P  represents  an  optional  switch  (at  the  end  of  the 

FRUN  command)  for  debugging  purposes.  When  the 
carriage  return  is  typed,  FRUN  prints  the  load 
address  of  the  program,  but  does  not  start  the 
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program.  The  foreground  job  must  be  explicitly 
started  with  the  RSUME  command  (see  Section 
2. 7. 5. 3).  For  example: 

.  FRUN  DRTR,'P 
LORDED  RT  125444 


If  ODT  is  used  with  the  foreground  job,  this 
feature  provides  the  means  for  determining  where 
the  job  actually  was  loaded. 

The  program  is  started  when  the  RSUME  command  is 
given,  allowing  the  programmer  to  examine  or 
modify  the  program  before  starting  it. 

If  another  foreground  job  is  active  when  the  FRUN  command  is  given,  an 
error  message  is  printed.  If  a  terminated  foreground  job  is  occupying 
memory,  that  region  is  first  reclaimed.  Then  if  the  file  indicated  is 
found  and  will  fit  in  memory,  the  job  is  installed  and  started 
immediately.  FRUN  destroys  the  background  job's  memory  image. 

Examples : 


FRUN  FI 


Runs  program  Fl.REL  stored  on  device  DK. 


FRU  DTI  :  F2 


Runs  F2.REL  which  is  on  DTI. 


SUSPEND 


2. 7. 5. 2  SUSPEND  Command  -  The  SUSPEND  command  is  used  to  stop 
execution  of  the  foreground  job. 

The  form  of  the  command  is: 

susIpend! 


No  arguments  are  required.  Foreground  I/O  transfers  in  progress  will 
be  allowed  to  complete;  however,  no  new  I/O  requests  will  be  issued 
and  no  completion  routines  will  be  entered  (see  Chapter  9  for  a 
discussion  of  completion  routines) .  Execution  of  the  job  can  be 
resumed  only  from  the  keyboard. 

Example : 


SUSPEND  Suspends  execution  of  the  foreground  job  currently 
running. 
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RSUME 


2 .7. 5. 3  RSUME  Command  -  The  RSUME  command  is  used  to  resume  execution 
of  the  foreground  job  where  it  was  suspended.  Any  completion  routines 
which  were  scheduled  while  the  foreground  was  suspended  are  entered  at 
this  time. 

The  form  of  the  command  is: 

rsu|me| 

No  arguments  are  required. 

Example : 

RSU  Resumes  execution  of  the  foreground  job  currently 

suspended. 


2.8  MONITOR  ERROR  MESSAGES 

The  following  error  messages  are  output  by  the  Keyboard  Monitor. 


Message 

7ADDR? 

7DAT? 

?ER  RD  OVLY? 

F? 

?F  ACTIVE? 

?FIL  NOT  FND? 

7FILE? 


Meaning 

Address  out  of  range  in  E  or  D  command . 

The  DATE  command  argument  was  illegal, 
or  no  argument  was  given  and  the  date 
has  not  yet  been  set. 

An  I/O  error  occurred  while  reading  a 
KMON  overlay  to  process  the  current 
command.  This  is  a  serious  error, 
indicating  that  the  system  file 
MONITR.SYS  is  unreadable. 

A  CTRL  F  was  typed  and  no  foreground  job 
exists. 

Neither  FRUN  nor  UNLOAD  may  be  used  when 
a  foreground  job  already  exists  and  is 
active . 

File  specified  in  R,  RUN,  GET,  or  FRUN 
command  not  found. 

No  file  named  where  one  is  expected. 


2-37 


Meaning 


System  Communication 


Message 

Meaning 

7HANDLR? 

Attempted  to  close  a  file  with  no 

handler  in  memory.  The  file  cannot  be 
closed. 

PILL  CMD? 

Illegal  Keyboard  Monitor  command  or 

command  line  too  long. 

?ILL  DEV? 

Illegal  or  nonexistent  device,  or  am 
attempt  was  made  to  make  a  device 
handler  resident  for  use  with  a 
foreground  job  (dev=F)  when  the 
Single-Job  Monitor  was  running. 

?N0  CLOCK? 

No  KW11L  clock  is  available  for  the  TIME 
command. 

?N0  FG? 

A  SUSPEND,  RSUME,  or  UNLOAD  FG  command 
was  given,  but  no  foreground  job  was  in 
memory . 

?OVR  COR? 

Attempt  to  GET  or  RUN  a  file  that  is  too 
big. 

7PARAMS? 

Bad  parameters  were  typed  to  the  SAVE 
command. 

?REL  FIL  I/O  ER? 

Either  the  program  requested  is  not  a 
REL  file  or  a  hardware  error  was 
encountered  trying  to  read  or  write  the 
file. 

?SV  FIL  I/O  ER? 

I/O  error  on  .SAV  file  in  SAVE  (output) 
or  R,  RUN,  GET,  or  FRUN  (input)  command. 

?SY  I/O  ER? 

I/O  error  on  system  device  (usually 
reading  or  writing  scratch  area) . 

?TIM? 

The  TIME  command  argument  was  illegal. 

The  following  messages  are  output  by  the  RT-11  Resident  Monitor  when 
an  unrecoverable  error  has  occurred.  Control  passes  to  the  Keyboard 
Monitor.  The  program  in  which  the  error  occurred  cannot  be  restarted 
with  the  RE  command.  To  execute  the  program  again ,  use  the  R  or  RUN 
command. 

The  format  for  fatal  monitor  error  messages  is: 


?M-text  PC 

where  PC  is  the  address-f2  of  the 

location  where  the  error  occurred. 

Note  that  ?M  errors  can  be  inhibited  in  certain  cases  by  the  use  of 
the  .SERR  macro;  see  Chapter  9  for  details. 

Message  Meaning 


7M-ILL  ADDR 

Under  the  F/B  Monitor,  an  address 
specified  in  a  monitor  call  was  odd  or 
was  not  within  the  job's  limits. 
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7M-BAD  FETCH 

?M— DIR  10  ERR 

7M-DIR  OVFLO 

7M-DIR  UNSAFE 

7M-FP  TRAP 

7M-ILL  CHAN 

7M-ILL  EMT 


Either  an  error  occurred  while  reading 
in  a  device  handler  from  SY,  or  the 
address  at  which  the  handler  was  to  be 
loaded  was  illegal. 

An  error  occurred  doing  I/O  in  the 
directory  of  a  device  (e.g. ,  .ENTER  on  a 
write- locked  device) . 

No  more  directory  segments  were 
available  for  expansion  (occurs  during 
file  creation  (.ENTER)). 

In  F/B  only,  this  message  may  appear  in 
addition  to  any  of  the  other  diagnostics 
listed  in  this  section.  It  indicates 
that  the  error  occurred  while  the  USR 
was  updating  a  device  directory.  One  or 
more  files  on  that  device  may  be  lost. 

A  floating-point  exception  trap 
occurred,  and  the  user  program  had  no 
•SFPA  exception  routine  active  (see 
Chapter  9) . 

A  channel  number  was  specified  which  was 
too  large. 

An  EMT  was  executed  which  did  not  exist; 
i.e.,  the  function  code  was  out  of 
bounds . 


?M— ILL  USR  The  USR  was  called  from  a  completion 

routine.  This  error  does  not  have  a 
soft  return  (i.e.,  .SERR  will  not 
inhibit  this  message;  see  Chapter  9) . 

7M-N0  DEV  A  READ/WRITE  operation  was  tried  but  no 

device  handler  was  in  memory  for  it. 

7M-0VLY  ERR  A  user  program  with  overlays  failed  to 

successfully  read  an  overlay. 


7M-SWAP  ERR 


?M— TRAP  TO  4 
?M— TRAP  TO  10 


A  hard  I/O  error  occurred  while  the 
system  was  attempting  to  swap  KMON  or 
the  USR.  This  is  usually  caused  by  a 
write-locked  system  device.  Under  the 
Single— Job  Monitor,  this  may  cause  the 
system  to  halt. 

The  job  has  referenced  illegal  memory, 
an  illegal  instruction  was  used,  etc. 
The  printed  PC  indicates  where  the 
failure  occurred.  .SERR  will  not  have 
an  effect  on  these  errors.  They  can  be 
intercepted  using  the  .TRPSET  programmed 
request  (see  Chapter  9) . 


If  CSI  errors  occur  and  input  was  from  the  console  terminal,  an  error 
message  is  printed  on  the  terminal. 
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Message 


Meaning 


?DEV  FUL? 


?ILL  CMD? 


?FIL  NOT  FND? 


?ILL  DEV? 


Output  file  will  not  fit. 

Input  file  was  not  found. 

Syntax  error. 

Device  specified  does  not  exist. 


2.8.1  Monitor  HALTS 

There  are  two  HALT  instructions  in  the  RT-11  VO 2  monitors,  one  each  in 
F/B  and  Single- Job.  The  Single-Job  Monitor  will  halt  only  if  I/O 
errors  occur  during  swap  operations  to  the  system  device.  If  the  S/J 
Monitor  halts,  look  for  a  write- locked  system  device. 

The  F/B  Monitor  will  halt  if  a  trap  to  location  4  occurs  or  if  I/O 
occurs  while  the  system  is  performing  critical  operations  from  which 
it  cannot  recover.  If  the  F/B  Monitor  halts,  look  for  use  of 
non-existent  devices,  traps  from  interrupt  service  routines,  or 
user-corrupted  queue  elements. 

The  monitor  halts  can  be  detected  by  their  address,  which  is  high  in 
memory,  above  the  resident  base  address  (location  54) . 
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TEXT  EDITOR 


The  Text  Editor  (EDIT)  is  used  to  create  and  modify  ASCII  source  files 
so  that  these  files  can  be  used  as  input  to  other  system  programs  such 
as  the  assembler  or  BASIC.  Controlled  by  user  commands  from  the 
keyboard ,  EDIT  reads  ASCII  files  from  a  storage  device ,  makes 
specified  changes  and  writes  ASCII  files  to  a  storage  device  or  lists 
them  on  the  line  printer  or  console  terminal.  EDIT  allows  efficient 
use  of  VT-11  display  hardware,  if  this  is  part  of  the  system 
configuration . 

The  Editor  considers  a  file  to  be  divided  into  logical  units  called 
pages.  A  page  of  text  is  generally  50-60  lines  long  (delimited  by 
form  feed  characters)  and  corresponds  approximately  to  a  physical  page 
of  a  program  listing.  The  Editor  reads  one  page  of  text  at  a  time 
from  the  input  file  into  its  internal  buffers  where  the  page  becomes 
available  for  editing.  Editing  commands  are  then  used  to: 

Locate  text  to  be  changed. 

Execute  and  verify  the  changes. 

Output  a  page  of  text  to  the  output  file. 

List  an  edited  page  on  the  line  printer  or  console  terminal. 


3.1  CALLING  AND  USING  EDIT 

To  call  EDIT  from  the  system  device  type: 

R  EDIT 

and  the  RETURN  key  in  response  to  the  dot  (.)  printed  by  the  monitor. 
EDIT  responds  with  an  asterisk  (*)  indicating  it  is  in  command  mode 
and  awaiting  a  user  command  string. 

Type  CTRL  C  to  halt  the  Editor  at  any  time  and  return  control  to  the 
monitor.  To  restart  the  Editor  type  .R  EDIT  or  the  .REENTER  command 
in  response  to  the  monitor's  dot.  The  contents  of  the  buffers  are 
lost  when  the  Editor  is  restarted. 
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3.2  MODES  OF  OPERATION 

Under  normal  usage ,  the  Editor  operates  in  one  of  two  different  modes: 
Command  Mode  or  Text  Mode,  In  Command  Mode  all  input  typed  on  the 
keyboard  is  interpreted  as  commands  instructing  the  Editor  to  perform 
some  operation.  In  Text  Mode  all  typed  input  is  interpreted  as  text 
to  replace ,  be  inserted  into,  or  be  appended  to  the  contents  of  the 
Text  Buffer. 

Immediately  after  being  loaded  into  memory  and  started ,  the  Editor  is 
in  Command  Mode.  An  asterisk  is  printed  at  the  left  margin  of  the 
console  terminal  page  indicating  that  the  Editor  is  waiting  for  the 
user  to  type  a  command.  All  commands  are  terminated  by  pressing  the 
ALTMODE  key  twice  in  succession.  Execution  of  commands  proceeds  from 
left  to  right.  Should  an  error  be  encountered  during  execution  of  a 
command  string,  the  Editor  prints  an  error  message  followed  by  an 
asterisk  at  the  beginning  of  a  new  line  indicating  that  it  is  still  in 
Command  Mode  and  awaiting  a  legal  command.  The  command  in  error  (and 
any  succeeding  commands)  is  not  executed  and  must  be  corrected  and 
retyped. 

Text  mode  is  entered  whenever  the  user  types  a  command  which  must  be 
followed  by  a  text  string.  These  commands  insert,  replace,  exchange, 
or  otherwise  manipulate  text;  after  such  a  command  has  been  typed, 
all  succeeding  characters  are  considered  part  of  the  text  string  until 
an  ALTMODE  is  typed.  The  ALTMODE  terminates  the  text  string  and 
causes  the  Editor  to  reenter  Command  Mode,  at  which  point  all 
characters  are  considered  commands  again. 

A  special  editing  mode,  called  Immediate  Mode,  can  be  used  whenever 
the  VT-11  display  hardware  is  running.  This  mode  is  described  in 
Section  3.7.2. 


3.3  SPECIAL  KEY  COMMANDS 

The  EDIT  key  commands  are  listed  in  Table  3-1.  Control  commands  are 
typed  by  holding  down  the  CTRL  key  while  typing  the  appropriate 
character. 


Table  3-1 
EDIT  Key  Commands 


Key 

Explanation 

ALTMODE 

Echoes  $.  A  single  ALTMODE  terminates  a  text 
string.  A  double  ALTMODE  executes  the  command 

string.  For  example. 

* G M 0 V  ft, 

CTRL  C 

Echoes  at  the  terminal  as  tC  and  a  carriage 
return.  Terminates  execution  of  EDIT  commands, 
and  returns  to  monitor  Command  Mode.  A  double 
CTRL  C  is  necessary  when  I/O  is  in  progress.  The 
REENTER  command  may  be  used  to  restart  the  Editor, 
but  the  contents  of  the  text  buffers  are  lost. 

(continued  on  next  page) 
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Table  3-1  (cont.) 

EDIT  Key  Commands 

Key 

Explanation 

CTRL  0 

Echoes  to  and  a  carriage  return.  Inhibits 
printing  on  the  terminal  until  completion  of  the 
current  command  string.  Typing  a  second  CTRL  0 
resumes  output. 

CTRL  U 

Echoes  tU  and  a  carriage  return.  Deletes  all  the 
characters  on  the  current  terminal  input  line. 
(Equivalent  to  typing  RUBOUT  back  to  the  beginning 
of  the  line.) 

RUBOUT 

Deletes  character  from  the  current  line;  echoes  a 
backslash  followed  by  the  character  deleted.  Each 
succeeding  RUBOUT  typed  by  the  user  deletes  and 
echoes  another  character.  An  enclosing  backslash 
is  printed  when  a  key  other  than  RUBOUT  is  typed. 
This  erasure  is  done  right  to  left  up  to  the  last 
carriage  return/line  feed  combination.  RUBOUT  may 
be  used  in  both  Command  and  Text  Modes. 

TAB 

Spaces  to  the  next  tab  stop.  Tab  stops  are 
positioned  every  eight  spaces  on  the  terminal; 
typing  the  TAB  key  causes  the  carriage  to  advance 
to  the  next  tab  position. 

CTRL  X 

Echoes  tX  and  a  carriage  return.  CTRL  X  causes 

the  Editor  to  ignore  the  entire  command  string 
currently  being  entered.  The  Editor  prints  a 

<CRXLF>  and  an  asterisk  to  indicate  that  the  user 
may  enter  another  command.  For  example: 

*  I RBCD 

EFGH~X 

* 

A  CTRL  U  would  only  cause  deletion  of  EFGH; 
CTRL  X  erases  the  entire  command. 

3.4  COMMAND  STRUCTURE 

EDIT  commands  fall  into  six  general  categories: 


Category 

Commands 

Section 

Input/Output 

Edit  Backup 

3. 6. 1.3 

Edit  Read 

3.6.1. 1 

Edit  Write 

3. 6. 1.2 

End  File 

3. 6. 1.9 

Exit 

3.6.1.10 

List 

3. 6. 1.7 

Next 

3. 6. 1.6 

Read 

3. 6. 1.4 

Verify 

3. 6. 1.8 

Write 

3. 6. 1.5 

Pointer  location 

Advance 

3. 6. 2. 3 

Beginning 

3. 6. 2.1 

Jump 

3. 6. 2. 2 
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Search 


Find 

Get 

Position 


3. 6. 3. 2 
3. 6. 3.1 

3.6.3. 3 


Text  modification  Change 

Delete 

exchange 


Insert 

Kill 


3. 6. 4. 4 

3. 6. 4. 2 

3. 6. 4. 5 
3. 6. 4.1 

3. 6. 4. 3 


Utility 


Edit  Console 
Edit  Display 
Edit  Version 
Execute  Macro 
Macro 


3.7.1 

3.7.1 


Save 

Unsave 


3. 6. 5. 5 
3. 6. 5. 4 
3. 6. 5. 3 

3. 6. 5.1 

3. 6. 5. 2 


Immediate  Mode 


ALTMODE 
CTRL  D 
CTRL  G 
CTRL  N 
CTRL  V 
RUBOUT 


3.7.2 

3.7.2 

3.7.2 

3.7.2 

3.7.2 

3.7.2 


The  general  format  for  the  first  five  categories  of  EDIT  commands  is: 


nCtext$ 


or 


nC$ 


where  n  represents  one  of  the  legal  arguments  listed  in  Table  3-2,  C 
is  a  one-  or  two- letter  command,  and  text  is  a  string  of  successive 
ASCII  characters. 

As  a  rule,  commands  are  separated  from  one  another  by  a  single 
ALTMODE;  however,  if  the  command  requires  no  text,  the  separating 
ALTMODE  is  not  necessary.  Commands  are  terminated  by  a  single 
ALTMODE;  typing  a  second  ALTMODE  begins  execution.  (ALTMODE  is  used 
differently  when  Immediate  Mode  is  in  effect;  Section  3.7.2  details 
its  use  in  this  case.) 

The  format  of  Display  Editor  commands  is  somewhat  different  from  the 
normal  editing  command  format,  and  is  described  in  Section  3.7. 


3.4.1  Arguments 

An  argument  is  positioned  before  a  command  letter  and  is  used  either 
to  specify  the  particular  portion  of  text  to  be  affected  by  the 
command  or  to  indicate  the  number  of  times  the  command  should  be 
performed.  With  some  commands,  this  specification  is  implicit  and  no 
arguments  are  needed;  other  editing  commands  require  an  argument. 
Table  3-2  lists  the  formats  of  arguments  which  are  used  by  commands  of 
this  second  type. 


3-4 


c 


Text  Editor 


Table  3-2 
Command  Arguments 


Format 

Meaning 

n 

n  stands  for  any  integer  in  the  range  -16383  to 
+16383  and  may,  except  where  noted,  be  preceded  by 
a  +  or  -.  If  no  sign  precedes  n,  it  is  assumed  to 
be  a  positive  number.  whenever  an  argument  is 
acceptable  in  a  command,  its  absence  implies  an 
argument  of  1  (or  -1  if  only  the  -  is  present) . 

0 

0  refers  to  the  beginning  of  the  current  line. 

/ 

/  refers  to  the  end  of  text  in  the  current  Text 
Buffer. 

= 

=  is  used  with  the  J,  D  and  C  commands  only  and 
represents  -n,  where  n  is  equal  to  the  length  of 
the  last  text  argument  used. 

The  roles  of  all  arguments  are  explained  more  specifically  in 
following  sections. 


3.4.2  Command  Strings 

All  EDIT  command  strings  are  terminated  by  two  successive  ALTMODE 
characters.  Spaces ,  carriage  returns  and  line  feeds  within  a  command 
string  may  be  used  freely  to  increase  command  readability  but  are 
ignored  unless  they  appear  in  a  text  string.  Commands  used  to  insert 
text  can  contain  text  strings  that  are  several  lines  long.  Each  line 
is  terminated  with  a  <CRXLF>  and  the  entire  command  is  terminated 
with  a  double  ALTMODE. 

executed  in  sequence.  For 


first  command  fourth 

command 


Execution  of  a  command  string  begins  when  the  double  ALTMODE  is  typed 
and  proceeds  from  left  to  right.  Except  when  part  of  a  text  string , 
spaces ,  carriage  return ,  line  feed,  and  single  ALTMODES  are  ignored. 
For  examples 

♦BGMOV  R 0 $  =  C C L R  Rl*fiV$* 


Several  commands  can  be  strung  together  and 
example , 


text  object 


text  object 


♦BGMOV  PC/ RB$- 
^  J  V 
second 
command 


2CR155KGCLR  &R2$$ 
_ 


third 
command 


fifth 

command 
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may  be  typed  as : 

*B$  GMOV  R0$ 

=  C C L R  Rl$ 
ft* 

with  equivalent  execution. 


3,4,3  The  Current  Location  Pointer 

Most  EDIT  commands  function  with  respect  to  a  movable  reference 
pointer  which  is  normally  located  between  the  most  recent  character 
operated  upon  and  the  next  character  in  the  buffer.  At  any  given  time 
during  the  editing  procedure,  this  pointer  can  be  thought  of  as 
representing  the  current  position  of  the  Editor  in  the  text.  Most 
commands  use  this  pointer  as  an  implied  argument.  Commands  are 
available  for  moving  the  pointer  anywhere  in  the  text,  thereby 
redefining  the  current  location  and  allowing  greater  facility  in  the 
use  of  other  commands. 


3.4.4  Character-  and  Line-Oriented  Command  Properties 

Edit  commands  are  line-oriented  or  character-oriented  depending  on  the 
arguments  they  accept.  Line-oriented  commands  operate  on  entire  lines 
of  text.  Character-oriented  commands  operate  on  individual  characters 
independent  of  what  or  where  they  are. 

When  using  character-oriented  commands,  a  numeric  argument  specifies 
the  number  of  characters  that  are  involved  in  the  operation.  Positive 
arguments  represent  the  number  of  characters  in  a  forward  direction 
(in  relation  to  the  pointer) ,  negative  arguments  the  number  of 
characters  in  a  backward  direction.  Carriage  return  and  line  feed 
characters  are  treated  the  same  as  any  other  character.  For  example, 
assume  the  pointer  is  positioned  as  indicated  in  the  following  text  (t 
represents  the  current  position  of  the  pointer) 2 

MOV  #VECT , R2  <  CR>  <  LF  >  + 

CLR  @R2<CRXLF> 

The  EDIT  command  -2J  backs  the  pointer  by  two  characters. 

MOV  #  VECT  ,  R2+<  C  R>  <  LF  > 

CLR  @R2<CRXLF> 

The  command  10J  advances  the  pointer  forward  by  ten  characters  and 
places  it  between  the  CR  and  LF  characters  at  the  end  of  the  second 
line. 

MOV  #  VECT  ,  R2  <  CRX  LF  > 

CLR  @R2<CR>t<LF> 

Finally,  to  place  the  pointer  after  the  "C"  in  the  first  line,  a  -14J 
command  is  used.  The  J  (Jump)  command  is  explained  in  Section  3.6. 2.2. 


MOV  #VEGT,R2<CRXLF> 

CLR  @R2<CRXLF> 
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When  using  line-oriented  commands,  a  numeric  argument  represents  the 
number  of  lines  involved  in  the  operation.  The  Editor  recognizes  a 
line  of  text  as  a  unit  when  it  detects  a  <CRXLF>  combination  in  the 
text.  When  the  user  types  a  carriage  return,  the  Editor  automatically 
inserts  a  line  feed.  Positive  arguments  represent  the  number  of  lines 
forward  (in  relation  to  the  pointer) ;  this  is  accomplished  by  counting 
carriage  return/line  feed  combinations  beginning  at  the  pointer.  So, 
if  the  pointer  is  at  the  beginning  of  a  line,  a  line-oriented  command 
argument  of  +1  represents  the  entire  line  between  the  current  pointer 
and  the  terminating  line  feed.  If  the  current  pointer  is  in  the 
middle  of  the  line,  an  argument  of  +1  represents  only  the  portion  of 
the  line  between  the  pointer  and  the  terminating  line  feed. 

For  example,  assume  a  buffer  of: 


MOV  -PC  ,R1<CRXLF> 

ADD  #DRIV-.  ,Rl<CRXLF> 
MOV  #VECT,R2<CRXLF> 

CLR  @R2<CRXLF> 


The  command  to  advance  the  pointer  one  line  (1A)  causes  the  following 
change : 

MOV  PC,R1<CRXLF> 

+  ADD  #DRIV— .  ,R1<CRXLF> 

MOV  #VECT  ,  R2  <CRXLF  > 

CLR  @R2<CRXLF> 


The  command  2A  moves  the  pointer  over  2  <CRXLF>  combinations: 


MOV  PC  ,R1<CRXLF> 

ADD  #DRIV-.  ,R1<CRXLF> 

MOV  •#  VECT  ,  R2  <  CR>  <  LF  > 

+CLR  @R2<CRXLF> 


Negative  line  arguments  reference  lines  in  a  backward  direction  (in 
relation  to  the  pointer) .  Consequently,  if  the  pointer  is  at  the 
beginning  of  the  line,  a  line  argument  of  —1  means  "the  previous  line" 
(moving  backward  past  the  first  <CRXLF>  and  up  to  but  not  including 
the  second  <CRXLF>;  if  the  printer  is  in  the  middle  of  a  line,  an 
argument  of  -1  means  the  preceding  1  1/2  lines.  Assume  the  buffer 
contains : 

MOV  PC,R1<CRXLF> 

ADD  #DRIV-.  ,R1<CRXLF> 

MOV  # VECT , R2  <  CR>  <LF  > 

CLR  @R2<CRXLF> 


A  command  of  -lA  backs  the  pointer  by  1  1/2  lines. 

MOV  PC,R1<CRXLF> 

t ADD  #DRIV-.  ,R1<CRXLF> 

MOV  #VECT,R2<CRXLF> 

CLR  @R2<CRXLF> 
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Now  a  command  of  -1A  backs  it  by  only  1  line. 


+MOV  PC,R1<CRXLF> 

ADD  #DRIV— .  ,R1<CRXLF> 
MOV  #VECT,R2<CRXLF> 

CLR  @R2<CRXLF> 


3.4.5  Command  Repetition 

Portions  of  a  command  string  may  be  executed  more  than  once  by 
enclosing  the  desired  portion  in  angle  brackets  (<>)  and  preceding  the 
left  angle  bracket  with  the  number  of  iterations  desired.  The 
structure  is: 

Cl$C2$n<C3$C4$>C5$$ 

where  Cl,  C2,...C5  represent  commands  and  n  represents  an  iteration 
argument.  Commands  Cl  and  C2  are  each  executed  once,  then  commands  C3 
and  C4  are  executed  n  times.  Finally  command  C5  is  executed  once  and 
the  command  line  is  finished.  The  iteration  argument  (n)  must  be  a 
positive  number  (1  to  16,383),  and  if  not  specified  is  assumed  to  be 
1.  If  the  number  is  negative  or  too  large,  an  error  message  is 
printed.  Iteration  brackets  may  be  nested  up  to  20  levels.  Command 
lines  are  checked  to  make  certain  the  brackets  are  correctly  used  and 
match  prior  to  execution. 

Essentially,  enclosing  a  portion  of  a  command  string  in  iteration 
brackets  and  preceding  it  with  an  iteration  argument  (n)  is  equivalent 
to  typing  that  portion  of  the  string  n  times.  For  examples 

is  equivalent  to  typings 

*BGRfifi*-DIB*-J-DIB#-J-DIBS-JVf$ 


ands 

*B3<2<RD>V>*$ 

is  equivalent  to  typings 

*6fiDRDVRDflDVRDfiDV$* 

The  following  bracket  structures  are  examples  of  legal  usages 

<<><<<><»>> 

<<<»><><> 


The  following  bracket  structures  are  examples  of  illegal  combinations 
which  will  cause  an  error  message  since  the  brackets  are  not  properly 
matched  s 


XX 

<<<>> 

During  command  repetition,  execution  proceeds  from  left  to  right  until 
a  right  bracket  is  encountered.  EDIT  then  returns  to  the  last  left 
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bracket  encountered,  decrements  the  iteration  counter  and  executes  the 
commands  within  the  brackets.  When  the  counter  is  decremented  to  0, 
EDIT  looks  for  the  next  iteration  count  to  the  left  and  repeats  the 
same  procedures.  The  overall  effect  is  that  EDIT  works  its  way  to  the 
innermost  brackets  and  then  works  its  way  back  again.  The  most  common 
use  for  iteration  brackets  is  found  in  commands  such  as  Unsave,  that 
do  not  accept  repeat  counts.  For  example: 


Assume  a  file  called  SAMP  (stored  on  device  DK)  is  to  be  read  and  the 
first  four  occurrences  of  the  instruction  MOV  #200, R0  on  each  of  the 
first  five  pages  are  to  be  changed  to  MOV  #244, R4,  The  following 
command  line  is  entered: 

♦  E B S fi M P $ 5 < N 4 < B G M 0 V  #208,  R0$=J$3<G0* =C4$>»EX$$ 


A 


The  command  line  contains  three  sets  of  iteration  loops  (A,B,C)  and  is 
executed  as  follows : 

Execution  initially  proceeds  from  left  to  right;  the  file  SAMP  is 
opened  for  input,  and  the  first  page  is  read  into  memory.  The  pointer 
is  moved  to  the  beginning  of  the  buffer  and  a  search  is  initiated  for 
the  character  string  MOV  #200, R0.  When  the  string  is  found,  the 
pointer  is  positioned  at  the  end  of  the  string,  but  the  =J  command 
moves  the  pointer  back  so  that  it  is  positioned  immediately  preceding 
the  string.  At  this  point,  execution  has  passed  through  each  of  the 
first  two  sets  of  iteration  loops  (A,B)  once.  The  innermost  loop  (C) 
is  next  executed  three  times,  changing  the  0s  to  4s.  Control  now 
moves  back  to  pick  up  the  second  iteration  of  loop  B,  and  again  moves 
from  left  to  right.  When  loop  C  has  executed  three  times,  control 
again  moves  back  to  loop  B.  When  loop  B  has  executed  a  total  of  4 
times,  control  moves  back  to  the  second  iteration  of  loop  A,  and  so 
forth  until  all  iterations  have  been  satisfied. 


3.5  MEMORY  USAGE 

The  memory  area  used  by  the  Editor  is  divided  into  four  logical 
buffers  as  follows: 

High  Memory 


Low  Memory 


MACRO  BUFFER 

SAVE 

BUFFER 

FREE 

MEMORY 

COMMAND  INPUT 

BUFFER 

TEXT 

BUFFER 
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The  Text  Buffer  contains  the  current  page  of  text  being  edited ,  and 
the  Command  Input  Buffer  holds  the  command  currently  being  typed  at 
the  terminal.  If  a  command  currently  being  entered  by  the  user  is 
within  10  characters  of  exceeding  the  space  available  in  the  Command 
Buffer,  the  message: 

*  CB  ALMOST  FULL  * 

is  printed.  If  the  command  can  be  completed  within  10  characters,  the 
user  may  finish  entering  the  command;  otherwise  he  should  type  the 
ALTMODE  key  twice  to  execute  that  portion  of  the  command  line  already 
completed.  The  message  is  printed  each  time  a  character  is  entered  in 
one  of  the  last  10  spaces. 

If  the  user  attempts  to  enter  more  than  10  characters  the  message: 

?CB  FULL? 

is  printed  and  all  commands  typed  within  the  last  10  characters  are 
ignored.  The  user  again  has  10  characters  of  available  space  in  which 
to  correct  the  condition. 

The  Save  Buffer  contains  text  stored  with  the  Save  (S)  command,  and 
the  Macro  Buffer  contains  the  command  string  macro  entered  with  the 
Macro  (M)  command.  (Both  commands  are  explained  in  Section  3.6.5.) 

The  Macro  and  Save  Buffers  are  not  allocated  space  until  an  M  or  S 
command  is  executed.  Once  an  M  or  S  command  is  executed,  a  0M  or  0U 
(Unsave)  command  must  be  executed  to  return  that  space  to  the  free 
area. 

The  size  of  each  buffer  automatically  expands  and  contracts  to 
accommodate  the  text  being  entered;  if  there  is  not  enough  space 
available  to  accommodate  required  expansion  of  any  of  the  buffers,  a 
"?*NO  ROOM*?"  error  message  is  typed. 


3.6  EDITING  COMMANDS 


3.6.1  Input/Output  Commands 

Input  commands  are  used  to  create  files  and  read  them  into  the  Text 
Buffer  where  they  become  available  for  editing  or  listing.  Output 
commands  cause  text  to  be  listed  on  the  console  terminal  or  line- 
printer  or  written  out  to  a  storage  device.  Some  commands  are 
specifically  designed  for  either  input  or  output  functions,  while  a 
few  commands  serve  both  purposes. 

Once  editing  is  completed  and  the  page  currently  in  the  Text  Buffer  is 
written  to  the  output  file,  that  page  of  text  is  unavailable  for 
further  editing  until  the  file  is  closed  and  reopened. 


3. 6.1.1  Edit  Read  -  The  Edit  Read  command  opens  an  existing  file  for 
input  and  prepares  it  for  editing. 
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The  form  of  the  command  is: 

ERdev : f ilnam. ext$ 

The-  string  argument  (dev: f ilnam. ext)  is  limited  to  19  characters  and 
specifies  the  file  to  be  opened.  If  no  device  is  specified,  DK:  is 
assumed.  If  a  file  is  currently  open  for  input,  that  file  is  closed; 
any  edits  made  to  the  file  are  preserved. 

Edit  Read  does  not  input  a  page  of  text  nor  does  it  affect  the 
contents  of  the  other  user  buffers  (see  Section  3.5.) 

Edit  Read  can  be  used  on  a  file  which  is  already  open  to  close  that 
file  for  input  and  reposition  EDIT  at  its  beginning.  The  first  Read 
command  following  any  Edit  Read  command  inputs  the  first  page  of  the 
file. 

Examples : 

*  E  R  D  T 1 : 5  ft  M  P .  M  ft  C  *  $  Opens  SAMP. MAC  on  device  DTI:  for  input. 
*ERSOURCE$S  Opens  SOURCE  on  device  DK:  for  input. 


3. 6. 1.2  Edit  Write  -  The  Edit  Write  command  sets  up  a  file  for 
output  of  newly  created  or  edited  text.  However,  no  text  is  output 
and  the  contents  of  the  user  buffers  are  not  affected.  Any  current 
output  files  are  closed. 

The  form  of  the  command  is : 

EWdev:f ilnam. ext [n] $ 

The  string  argument  (dev:filnam.ext [n] )  is  limited  to  19  characters 
and  is  the  name  to  be  assigned  to  the  output  file  being  opened.  If 
dev:  is  not  specified,  DK:  is  assumed.  [n]  is  optional  and 
represents  the  length  of  the  file  to  be  opened.  If  not  specified,  the 
largest  available  space  is  used. 

If  a  file  with  the  same  name  already  exists  on  the  device,  the  old 
file  is  deleted  when  an  EXit,  End  File  or  another  Edit  Write  command 
is  executed. 

Examples : 

*EMDK : TEST.  MRC$$  Opens  the  file  TEST. MAC  on  device  DK: 

for  output. 

+EWFILE.  BRSC11]$$  Opens  the  file  FILE. BAS  (allocating  11 

blocks)  on  the  device  DK:  for  output. 


3.6.1. 3  Edit  Backup  -  The  Edit  Backup  command  is  used  to  open  an 
existing  file  for  editing  and  at  the  same  time  create  a  backup  version 
of  the  file.  No  text  is  read  or  written  with  this  command. 
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The  form  of  the  command  is: 


EBdevjfilnam.ext [n] $ 


The  device  designation ,  filename  and  extension  are  limited  to  19 
characters.  If  dev:  is  not  specified,  DK:  is  assumed,  [n]  is 
optional  and  represents  the  length  of  the  file  to  be  opened;  if  not 
specified,  one-half  the  largest  available  space  is  used. 

The  file  indicated  in  the  command  line  must  already  exist  on  the 
device  designated  since  text  will  be  read  from  this  file  as  input.  At 
the  same  time,  an  output  file  is  opened  under  the  same  filename  and 
extension.  After  an  EB  command  has  been  successfully  executed,  the 
original  file  (used  as  input)  is  renamed  with  the  current  filename  and 
a  ,BAK  extension;  any  previous  file  with  this  filename  and  a  ,BAK 
extension  is  deleted.  The  new  output  file  is  closed  and  assigned  the 
name  as  specified  in  the  EB  command.  This  renaming  of  files  takes 
place  whenever  an  Exit,  End  File,  Edit  Read,  Edit  Write  or  Edit  Backup 
command  is  executed. 

Examples : 


*EBSV  :BR51.  MACS*  Opens  BAS1.MAC  on  SY.  When  editing  is 

complete,  the  old  BAS1.MAC  becomes 
BAS1.BAK  and  the  new  file  becomes 
BAS 1 • MAC •  Any  previous  version  of 
BASl.BAK  is  deleted. 


*EBBRS2.  BftSt 15 1**  Opens  BAS2.BAS  on  DK  (allocating  15 

blocks).  When  editing  is  complete,  the 
old  BAS 2 .BAS  is  labeled  BAS2.BAK  and  the 
new  file  becomes  BAS2.BAS.  Any  previous 
version  of  BAS2.BAK  is  deleted. 


In  EB,  ER  and  EW  commands,  leading  spaces  between  the  command  and  the 
filename  are  illegal  (the  filename  is  considered  to  be  a  text  string) . 
All  dev:file.ext  specifications  for  EB,  ER  and  EW  commands  conform  to 
the  RT-11  conventions  for  file  naming  and  are  identical  to  filenames 
entered  in  command  strings  used  with  other  system  programs. 


3. 6 .1.4  Read  -  The  Read  command  (R)  causes  a  page  of  text  to  be  read 
from  the  input  file  (previously  specified  in  an  ER  or  EB  command)  and 
appended  to  the  current  contents,  if  any,  of  the  Text  Buffer. 

The  form  of  the  command  is: 

R 

No  arguments  are  used  with  the  R  command  and  the  pointer  is  not  moved. 
Text  is  input  until  one  of  the  following  conditions  is  met: 

1.  A  form  feed  character,  signifying  the  end  of  the  page,  is 
encountered.  At  this  point,  the  form  feed  will  be  the  last 
character  in  the  buffer;  or 
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2.  The  Text  Buffer  is  within  500  characters  of  being  full. 
(When  this  condition  occurs ,  Read  inputs  up  to  the  next 
<CRXLF>  combination ,  then  returns  to  Command  Mode.  An 
asterisk  is  printed  as  though  the  Read  were  complete ,  but 
text  will  not  have  been  fully  input) ;  or 

3.  An  end-of-file  condition  is  detected,  (the  *EOF*  message  is 
printed  when  all  text  in  the  file  has  been  read  into  memory 
and  no  more  input  is  available) . 

The  maximum  number  of  characters  which  can  be  brought  into  memory  with 
an  R  command  is  approximately  6,000  for  an  8K  system.  Each  additional 
4K  of  memory  allows  approximately  8,000  additional  characters  to  be 
input.  An  error  message  is  printed  if  the  Read  exceeds  the  memory 
available  or  if  no  input  is  available. 


3. 6. 1.5  Write  -  The  Write  command  (W)  moves  lines  of  text  from  the 
Text  Buffer  to  the  output  file  (as  specified  in  the  EW  or  EB  command). 
The  format  of  the  command  is  s 


nW  Write  all  characters  beginning  at  the  pointer  and 

ending  at  the  nth  <CRXLF>  to  the  output  file. 

-nW  Write  all  characters  beginning  on  the  -nth  line  and 
terminating  at  the  pointer  to  the  output  file. 

0W  Write  the  text  from  the  beginning  of  the  current  line 
to  the  pointer. 

/W  Write  the  text  from  the  pointer  to  the  end  of  the 

buffer. 


The  pointer  is  not  moved  and  the  contents  of  the  buffer  are  not 
affected.  If  the  buffer  is  empty  when  the  Write  is  executed,  no 
characters  are  output. 


Examples : 


*5W$$ 


Writes  the  next  5  lines  of  text  starting 
at  the  pointer,  to  the  current  output 
file. 


*-2W$$ 


Writes  the  previous  2  lines  of  text, 
ending  at  the  pointer,  to  the  current 
output  file. 


r 


current 


Writes  the  entire  Text  Buffer  to  the 
current  output  file. 
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3. 6 .1.6  Next  -  The  Next  command  acts  as  both  an  input  and  output 
command  since  it  performs  both  functions.  First  it  writes  the  current 
Text  Buffer  to  the  output  file,  then  clears  the  buffer ,  and  finally 
reads  in  the  next  page  of  the  input  file.  The  Next  command  can  be 
repeated  n  times  by  specifying  an  argument  before  the  command.  The 
command  format  is : 


nN 


Next  accepts  only  positive  arguments  (n)  and  leaves  the  pointer  at  the 
beginning  of  the  buffer.  If  fewer  than  n  pages  are  available  in  the 
input  file,  all  available  pages  are  input  to  the  buffer,  output  to  the 
current  file,  and  deleted  from  the  buffer?  the  pointer  is  left 
positioned  at  the  beginning  of  an  empty  buffer,  and  an  error  message 
is  printed.  This  command  is  equivalent  to  a  combination  of  the 
Beginning,  Write,  Delete  and  Read  commands  (B/W/DR) .  Next  can  be  used 
to  space  forward,  in  page  increments,  through  the  input  file. 


Example 


Writes  the  contents  of  the  current  Text 
Buffer  to  the  output  file.  Read  and 
write  the  next  page  of  text.  Clear  the 
buffer  and  then  read  in  another  page. 


*2N$$ 


3. 6. 1.7  List  -  The  List  command  prints  the  specified  number  of  lines 
on  the  console  terminal.  The  format  of  the  command  is: 


nL 


Print  all  characters  beginning  at  the 
pointer  and  ending  with  the  nth 
<CRXLF>. 


•nL 


Print  all  characters  beginning  with  the 
first  character  on  the  -nth  line  and 
terminating  at  the  pointer. 


OL 


Print  from  the  beginning  of  the  current 
line  up  to  the  pointer. 


/L 


Print  from  the  pointer  to  the  end  of  the 
buffer. 


The  pointer  is  not  moved  after  the  command  is  executed. 


Examples : 


*-2L$$ 


Prints  all  characters  starting  at  the 
second  preceding  line  and  ending  at  the 
pointer. 


*4L$$ 


Prints  all  characters  beginning  at  the 
pointer  and  terminating  at  the  4  th 
<CRXLF>. 


Assuming  the  pointer  location  is : 

MOVB  5 (Rl) , @R2 
ADD+  R1,(R2)  + 
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The  command: 

*-lL$S 

Prints  the  previous  1  1/2  lines  up  to  the  pointer: 

MOVB  5(Rl),@R2 
ADD 


3. 6 • 1.8  Verify  -  The  Verify  command  prints  the  current  text  line 
(the  line  containing  the  pointer)  on  the  terminal.  The  position  of 
the  pointer  within  the  line  has  no  effect  and  the  pointer  does  not 
move.  The  command  format  is: 

V 

No  arguments  are  used.  The  V  command  is  equivalent  to  a  OLL  (List) 
command. 

Example : 


*V$$  The  command  causes  the  current  line  of 

RDD  Rl,  <R2)  +  text  to  be  printed. 


3. 6. 1.9  End  File  -  The  End  File  command  closes  the  current  output 
file.  This  command  does  no  input/output  operations  and  does  not  move 
the  pointer.  The  buffer  contents  are  not  affected.  The  output  file 
is  closed ,  containing  only  the  text  previously  output. 

The  form  of  the  command  is: 

EF 

No  arguments  are  used.  Note  that  an  implied  EF  command  is  included  in 
EW  and  EB  commands. 


3.6.1.10  EXit  -  The  EXit  command  is  used  to  terminate  editing ,  copy 
the  remainder  of  the  input  file  to  the  output  file,  and  return  control 
to  the  monitor.  It  performs  consecutive  Next  commands  until  the  end 
of  the  input  file  is  reached ,  then  closes  both  the  input  and  output 
files. 

The  command  format  is : 

EX 

No  arguments  are  used.  Essentially,  Exit  is  used  to  copy  the 
remainder  of  the  input  file  into  the  output  file  and  return  to  the 
monitor.  Exit  is  legal  only  when  there  is  an  output  file  open.  If  an 
output  file  is  not  open  and  it  is  desired  to  terminate  the  editing 
session,  return  to  the  monitor  with  CTRL  C. 
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NOTE 

An  EF  or  EX  command  is  necessary  in 
order  to  make  an  output  file  permanent. 

If  CTRL  C  is  used  to  return  to  the 
monitor  without  a  prior  execution  of  an 
EF  command,  the  current  output  file  is 
not  saved,  (It  can  however,  be  made 
permanent  using  the  monitor  CLOSE 
command;  see  Section  2, 7, 2, 5,) 

An  example  of  the  contrasting  uses  of  the  EF  and  EX  commands  follows. 
Assume  an  input  file,  SAMPLE,  contains  several  pages  of  text.  The 
user  wishes  to  make  the  first  and  second  pages  of  the  file  into 
separate  files  called  SAMI  and  SAM2 ,  respectively;  the  remaining 
pages  of  text  will  then  make  up  the  file  SAMPLE,  This  can  be  done 
using  these  commands: 

*EWSRM1$$ 

*ERSRMPLE$$ 

*  R  N  E  F  $  $ 

*EWSRM2$$ 

♦NEF** 

*EWSRMPLE$EX$$ 


The  user  might  note  that  the  EF  commands  are  not  necessary  in  this 
example  since  the  EW  command  closes  a  currently  open  output  file 
before  opening  another. 


3.6,2  Pointer  Relocation  Commands 

Pointer  relocation  commands  allow  the  current  location  pointer  to  be 
moved  within  the  Text  Buffer, 


3. 6. 2.1  Beginning  -  The  Beginning  command  moves  the  current  location 
pointer  to  the  beginning  of  the  Text  Buffer. 

The  command  format  is : 

B 

There  are  no  arguments. 

For  example,  assume  the  buffer  contains: 

5 (Rl) , @R2 
R1,(R2)+ 

6^1)  ,  @R2 


MOVB 

ADD 

CLR 

MOVB 
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The  B  command: 


moves  the  pointer  to  the  beginning  of  the  Text  Buffer: 

+  MOVB  5  (Rl)  /  @R2 
ADD  R1,(R2)+ 

CLR  @R2 

MOVB  6(Rl),@R2 


3. 6.2*2  Jump  -  The  Jump  command  moves  the  pointer  over  the  specified 
number  of  characters  in  the  Text  Buffer. 


The 

form  of  the 

command  is: 

(+ 

or  -)  nJ 

Move  the  pointer 
characters • 

(backward  or 

forward)  n 

OJ 

Move  the  pointer  to 
line  (equivalent  to 

the  beginning  of 
OA)  . 

the  current 

/J 

Move  the  pointer  to 
(equivalent  to  /A) . 

the  end  of  the 

Text  Buffer 

=J 

Move  the  pointer  backward  n  characters,  where  n 
equals  the  length  of  the  last  text  argument  used. 

Negative  arguments  move  the  pointer  toward  the  beginning  of  the 

buffer ,  positive  arguments  toward  the  end.  Jump  treats  carriage 

return ,  line  feed,  and  form  feed  characters  the  same  as  any  other 

character,  counting  one  buffer  position  for  each. 

Examples : 

Moves  the  pointer  ahead  three 

characters. 

Moves  the  pointer  back  four  characters. 

*B$GRBC$=J$s  Move  the  pointer  so  that  it  immediately 

precedes  the  first  occurrence  of  'ABC* 
in  the  buffer. 


3.6. 2. 3  Advance  -  The  Advance  command  is  similar  to  the  Jump  command 
except  that  it  moves  the  pointer  a  specified  number  of  lines  (rather 
than  single  characters)  and  leaves  it  positioned  at  the  beginning  of 
the  line. 

The  form  of  the  command  is : 

nA  Advance  the  pointer  forward  n  lines  and 

position  it  at  the  beginning  of  the  nth 
line. 
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-nA  Move  the  pointer  backward  past  n 

<CRXLF>  combinations  and  position  it  at 
the  beginning  of  the  -nth  line. 

OA  Advance  the  pointer  to  the  beginning  of 

the  current  line  (equivalent  to  OJ) . 

/A  Advance  the  pointer  to  the  end  of  the 

Text  Buffer  (equivalent  to  /J) . 

Examples  s 

Moves  the  pointer  ahead  three  lines. 

Assuming  the  buffer  contains : 

CLR  @R2 

+ 

The  command: 

Moves  the  pointer  to: 

+CLR  @R2 


3.6.3  Search  Commands 

Search  commands  are  used  to  locate  specific  characters  or  strings  of 
characters  within  the  Text  Buffer. 


3. 6. 3.1  Get  -  The  Get  command  starts  at  the  pointer  and  searches  the 
current  Text  Buffer  for  the  nth  occurrence  of  a  specified  text  string. 
If  the  search  is  successful,  the  pointer  is  left  immediately  following 
the  nth  occurrence  of  the  text  string.  If  the  search  fails,  an  error 
message  is  printed  and  the  pointer  is  left  at  the  end  of  the  Text 
Buffer.  The  format  of  the  command  is : 

nGtext$ 

The  argument  (n)  must  be  positive  and  is  assumed  to  be  1  if  not 
otherwise  specified.  The  text  string  may  be  any  length  and 
immediately  follows  the  G  command.  The  search  is  made  on  the  portion 
of  the  text  between  the  pointer  and  the  end  of  the  buffer. 

Example : 

Assuming  the  buffer  contains: 


MOV 

PC,R1 

ADD 

#DRIV— . ,R1 

MOV 

# VECT , R2 

CLR 

@R2 

MOVB 

5 (Rl) , @R2 

ADD 

Rl, (R2)+ 

CLR 

@R2 

MOVB 

6 (Rl) , @R2 
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The  command: 

*GRDD$$ 

positions  the  pointer  at: 

ADD.  #DRIV- . ,R1 

The  command: 

*3G0R2** 

positions  the  pointer  at: 

ADD  R1,(R2)+ 

CLR  @R2+ 

After  search  commands,  the  pointer  is  left  immediately  following  the 
text  object.  Using  a  search  command  in  combination  with  =J  will  place 
the  pointer  before  the  text  object,  as  follows: 

*GTEST*=J** 

This  command  combination  places  the  pointer  before  'TEST'. 


3. 6. 3. 2  Find  -  The  Find  command  starts  at  the  current  pointer  and 
searches  the  entire  input  file  for  the  nth  occurrence  of  the  text 
string.  If  the  nth  occurrence  of  the  text  string  is  not  found  in  the 
current  buffer,  a  Next  command  is  automatically  performed  and  the 
search  is  continued  on  the  new  text  in  the  buffer.  When  the  search  is 
successful,  the  pointer  is  left  immediately  following  the  nth 
occurrence  of  the  text  string.  If  the  search  fails  (i.e.,  the 
end-of-file  is  detected  for  the  input  file  and  the  nth  occurrence  of 
the  text  string  has  not  been  found) ,  an  error  message  is  printed  and 
the  pointer  is  left  at  the  beginning  of  an  empty  Text  Buffer. 

The  form  of  the  command  is : 

nFtext$ 

The  argument  (n)  must  be  positive  and  is  assumed  to  be  1  if  not 
otherwise  specified. 

By  deliberately  specifying  a  nonexistent  search  string,  the  user  can 
close  out  his  file;  that  is,  he  can  copy  all  remaining  text  from  the 
input  file  to  the  output  file. 

Find  is  a  combination  of  the  Get  and  Next  commands. 

Example : 

*  2  F  M  0  V  B  6  <  R 1  >  <  @  R  2  $  f  Searches  the  entire  input  file  for 

the  second  occurrence  of  the  text 
string  MOVB  6(Rl),@R2.  Each 

unsuccessfully  searched  buffer  is 
written  to  the  output  file. 


3-19 


Text  Editor 


3.6. 3. 3  Position  -  The  Position  command  searches  the  input  file  for 
the  nth  occurrence  of  the  text  string.  If  the  desired  text  string  is 
not  found  in  the  current  buffer ,  the  buffer  is  cleared  and  a  new  page 
is  read  from  the  input  file.  The  format  of  the  command  is: 

nPtext$ 

The  argument  (n)  must  be  positive,  and  is  assumed  to  be  1  if  not 
otherwise  specified.  When  a  P  command  is  executed  the  current 
contents  of  the  buffer  are  searched  from  the  location  of  the  pointer 
to  the  end  of  the  buffer.  If  the  search  is  unsuccessful,  the  buffer 
is  cleared  and  a  new  page  of  text  is  read  and  the  cycle  is  continued. 

If  the  search  is  successful,  the  pointer  is  positioned  after  the  nth 
occurrence  of  the  text.  If  it  is  not,  the  pointer  is  left  at  the 
beginning  of  an  empty  Text  Buffer. 

The  Position  command  is  a  combination  of  the  Get,  Delete  and  Read 
commands;  it  is  most  useful  as  a  means  of  placing  the  location 
pointer  in  the  input  file.  For  example,  if  the  aim  of  the  editing 
session  is  to  create  a  new  file  from  the  second  half  of  the  input 
file,  a  Position  search  will  save  time. 

The  difference  between  the  Find  and  Position  commands  is  that  Find 
writes  the  contents  of  the  searched  buffer  to  the  output  file  while 
Position  deletes  the  contents  of  the  buffer  after  it  is  searched. 

Example: 

+PRDD  Rl* <R2>*$*  Searches  the  entire  input  file  for  the 

specified  string  ignoring  the 
unsuccessfully  searched  buffers. 


3.6.4  Text  Modification  Commands 

The  following  commands  are  used  to  insert,  relocate,  and  delete  text 
in  the  Text  Buffer. 


3. 6. 4.1  Insert  -  The  Insert  command  causes  the  Editor  to  enter  Text 
Mode  and  allows  text  to  be  inserted  immediately  following  the  pointer. 
Text  is  inserted  until  an  ALTMODE  is  typed  and  the  pointer  is 
positioned  immediately  after  the  last  character  of  the  insert.  The 
command  format  is : 

Itext$ 

No  arguments  are  used  with  the  Insert  command,  and  the  text  string  is 
limited  only  by  the  size  of  the  Text  Buffer  and  the  space  available. 
All  characters  except  ALTMODE  are  legal  in  the  text  string.  ALTMODE 
terminates  the  text  string. 

NOTE 

Forgetting  to  type  the  I  command  will 
cause  the  text  entered  to  be  executed  as 
commands . 
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EDIT  automatically  protects  against  overflowing  the  Text  Buffer  during 
an  Insert.  If  the  I  command  is  the  first  command  in  a  multiple 
command  line,  EDIT  ensures  that  there  will  be  enough  space  for  the 
Insert  to  be  executed  at  least  once.  If  repetition  of  the  command 
exceeds  the  available  memory,  an  error  message  is  printed. 

Example  s 


♦  I MOV  #BIJFF,  R2 

MOV  #LINE,R1 

MOVE:  -1<R2>,  R®$* 

* 


Inserts  the  specified  text  at 
the  current  location  of  the 
pointer  and  leaves  the  pointer 
positioned  after  RO. 


3. 6. 4. 2  Delete  -  The  Delete  command  removes  a  specified  number  of 
characters  from  the  Text  Buffer.  Characters  are  deleted  starting  at 
the  pointer;  upon  completion,  the  pointer  is  positioned  at  the  first 
character  following  the  deleted  text. 


The 

form 

of  the  command  is: 

(  + 

or  -) 

nD 

Delete  n  characters  (forward  or  backward 
from  the  pointer) . 

OD 

Delete  from  beginning  of  current  line  to 
the  pointer  (equivalent  to  OK) . 

/D 

Delete  from  pointer  to  end  of  Text 
Buffer  (equivalent  to  /K) . 

=D 

Delete  -n  characters,  where  n  equals  the 
length  of  the  last  text  argument  used. 

Examples : 

*  -  2  D  $  $ 

Deletes  the  two  characters  immediately 
preceding  the  pointer. 

* B $ F M 0 V  R1$  =  D* 

Deletes  the  text  string  'MOV  Rl'.  (=D 
used  in  combination  with  a  search 

command  will  delete  the  indicated  text 
string) . 


Assuming  a  buffer  of: 

ADD  R1 , (R2 ) + 

CLR  R2 

the  command: 

*0D$$ 

leaves  the  buffer  with: 

ADD  Rl,(R2)+ 

l@R2 
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3. 6. 4. 3  Kill  -  The  Kill  command  removes  n  lines  from  the  Text 
Buffer.  Lines  are  deleted  starting  at  the  location  pointer;  upon 
completion  of  the  command,  the  pointer  is  positioned  at  the  beginning 
of  the  line  following  the  deleted  text.  The  command  format  is: 


Example : 


nK 


-nK 


OK 


/K 


*2K$* 


Delete  lines  beginning  at  the  pointer 
and  ending  at  the  nth  <CRXLF>. 

Delete  lines  beginning  with  the  first 
character  in  the  -nth  line  and  ending  at 
the  pointer. 

Delete  from  the  beginning  of  the  current 
line  to  the  pointer  (equivalent  to  OD) . 


Delete  from  the  pointer  to  the  end 
the  Text  Buffer  (equivalent  to  /D) . 


of 


Delete  lines  starting  at  the  current 
location  pointer  and  ending  at  the  2nd 
<CRXLF>. 


Assuming  a  buffer  of: 


ADD 

CLR^ 

MOVB 


Rl, (R2)+ 
@R2 

6  (Rl)  ,  @R2 


the  command: 

+  /K$* 

alters  the  contents  of  the  buffer  to: 


ADD 

CLR+ 


Rl, (R2)+ 


Kill  and  Delete  commands  perform  the  same  function,  except  that  Kill 
is  line-oriented  and  Delete  is  character-oriented. 


3. 6. 4. 4  Change  -  The  Change  command  replaces  n  characters,  starting 
at  the  pointer,  with  the  specified  text  string  and  leaves  the  pointer 
positioned  immediately  following  the  changed  text. 

The  form  of  the  command  is: 


(+  or  -)  nCtext$ 
0Ctext$ 

/Ctext$ 


Replace  n  characters  (forward  or  backward  from  the 
pointer)  with  the  specified  text. 

Replace  the  characters  from  the  beginning  of  the 
line  up  to  the  pointer  with  the  specified  text 
(equivalent  to  OX) . 

Replace  the  characters  from  the  pointer  to  the  end 
of  the  buffer  with  the  specified  text  (equivalent 
to  /X). 
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=Ctext$  Replace  -n  characters  with  the  indicated  text 
string ,  where  n  represents  the  length  of  the  last 
text  argument  used* 

The  size  of  the  text  is  limited  only  by  the  size  of  the  Text  Buffer 
and  the  space  available.  All  characters  are  legal  except  ALTMODE 
which  terminates  the  text  string. 

If  the  C  command  is  to  be  executed  more  than  once  (i.e.,  it  is 
enclosed  in  angle  brackets)  and  if  there  is  enough  space  available  so 
that  the  command  can  be  entered,  it  will  be  executed  at  least  once 
(provided  it  appears  first  in  the  command  string) .  If  repetition  of 
the  command  exceeds  the  available  memory,  an  error  message  is  printed. 
The  Change  command  is  identical  to  executing  a  Delete  command  followed 
by  an  Insert  (nDItext$) . 

Examples : 


*5C#VECT$$ 


Replaces  the  five  characters  to  the 
right  of  the  pointer  with  #VECT. 


Assuming  a  buffer  of: 


CLR 

MOV. 


@R2 

5 (Rl) , @R2 


The  command: 


*0CRDDB$$ 


leaves  the  buffer  with: 


CLR 

ADDB+ 


@R2 

5 (Rl) , @R2 


=C  can  be  used  in  conjunction  with  a  search  command  to  replace  a 
specific  text  string  as  follows: 


* G F I F T V : $  =  CFI VE  :  $ 


Find  the  occurrence  of  the  text  string 
FIFTY:  and  replace  it  with  the  text 
string  FIVE:. 


3.6. 4.5  Exchange  -  The  Exchange  command  exchanges  n  lines,  beginning 
at  the  pointer,  with  the  indicated  text  string  and  leaves  the  pointer 
positioned  after  the  changed  text. 

The  form  of  the  command  is : 

nXtext$  Exchange  all  characters  beginning  at  the  pointer 
and  ending  at  the  nth  <CRXLF>  with  the  indicated 
text. 

-nXtext$  Exchange  all  characters  beginning  with  the  first 
character  on  the  -nth  line  and  ending  at  the 
pointer  with  the  indicated  text. 


0Xtext$  Exchange  the  current  line  from  the  beginning  to 
the  pointer  with  the  specified  text  (equivalent  to 
OC)  . 
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/Xtext$  Exchange  the  lines  from  the  pointer  to  the  end  of 
the  buffer  with  the  specifed  text  (equivalent  to 
/C). 


All  characters  are  legal  in  the  text  string  except  ALTMODE  which 
terminates  the  text. 

The  Exchange  command  is  identical  to  a  Kill  command  followed  by  an 
Insert  (nKItext$) ,  and  accepts  all  legal  line-oriented  arguments. 


If  the  X  command  is  enclosed  within  angle  brackets  so  that  it  will  be 
executed  more  than  once,  and  if  there  is  enough  memory  space  available 
so  that  the  X  command  can  be  entered,  it  will  be  executed  at  least 
once  (provided  it  is  first  in  the  command  string) ,  If  repetition  of 
the  command  exceeds  the  available  memory,  an  error  message  is  printed. 


Example : 


*  2  X  fl  D  D  Rl,  <R2>  + 

CLR  &R2 

$$ 

* 


Exchanges  the  two  lines  to 
the  right  of  the  pointer  location 
with  the  text  string. 


3.6.5  Utility  Commands 


3. 6. 5.1  Save  -  The  Save  command  starts  at  the  pointer  and  copies  the 
specified  number  of  lines  into  the  Save  Buffer  (described  previously 
in  Section  3.5). 

The  form  of  the  command  is  s 

nS 

The  argument  (n)  must  be  positive.  The  pointer  position  does  not 
change  and  the  contents  of  the  Text  Buffer  are  not  altered.  Each  time 
a  Save  is  executed,  the  previous  contents  of  the  Save  Buffer,  if  any, 
are  destroyed.  If  the  Save  command  causes  an  overflow  of  the  Save 
Buffer,  an  error  message  is  printed. 

Examples 

Assume  the  Text  Buffer  contains  the  following  assembly  language 
subroutine : 
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; SUBROUTINE  MSGTYP 

; WHEN  CALLED,  EXPECTS  RO  TO  POINT  TO  AN 
; ASCI I  MESSAGE  THAT  ENDS  IN  A  ZERO  BYTE, 
; TYPES  THAT  MESSAGE  ON  THE  USER  TERMINAL 


MSGTYP: 
MLOOP : 

MDONE : 

The  command: 


.ASECT 
.=1000 
TSTB  (%0) 

BEQ  MDONE 
TSTB  @#177564 
BPL  MLOOP 

MOVB  (%0)+, @#177566 
BR  MSGTYP 
RTS  %7 


; DONE? 

; YES- RETURN 

;NO-IS  TERMINAL  READY? 
; NO-WAIT 

; YES  PRINT  CHARACTER 
;LOOP 
; RETURN 


stores  the  entire  subroutine  in  the  Save  Buffer;  it  may  then  be 
inserted  in  a  program  wherever  needed  by  using  the  U  command. 


3. 6. 5. 2  Unsave  -  The  Unsave  command  inserts  the  entire  contents  of 
the  Save  Buffer  into  the  Text  Buffer  at  the  pointer  location  and 
leaves  the  pointer  positioned  following  the  inserted  text. 

The  form  of  the  command  is : 

U  Insert  in  the  Text  Buffer  the  contents  of  the  Save 
Buffer. 

0U  Clear  the  Save  Buffer  and  reclaim  the  area  for  text. 
Zero  is  the  only  legal  argument  to  the  U  command. 

The  contents  of  the  Save  Buffer  are  not  destroyed  by  the  Unsave 
command  (only  by  the  0U  command)  and  may  be  Unsaved  as  many  times  as 
desired. 

If  there  is  no  text  in  the  Save  Buffer  and  the  U  command  is  given,  the 
?*NO  TEXT*?  error  message  is  printed.  If  the  Unsave  command  causes 
an  overflow  of  the  Text  Buffer,  the  ?*NO  ROOM*?  error  message  is 
displayed. 


3. 6. 5. 3  Macro  -  The  Macro  command  inserts  a  command  string  into  the 
EDIT  Macro  Buffer.  The  Macro  command  is  of  the  form: 

M/command  string/  Store  the  command  string  in  the  Macro 

Buffer. 

Clear  the  Macro  Buffer  and  reclaim  the 
or  area  for  text. 

M// 

/represents  the  delimiter  character.  The  delimiter  is  always  the 
first  character  following  the  M  command,  and  may  be  any  character 
which  does  not  appear  in  the  Macro  command  string  itself. 
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Starting  with  the  character  following  the  delimiter,  EDIT  places  the 
Macro  command  string  characters  into  its  internal  Macro  Buffer  until 
the  delimiter  is  encountered  again.  At  this  point,  EDIT  returns  to 
Command  Mode.  The  Macro  command  does  not  execute  the  Macro  string; 
it  merely  stores  the  command  string  so  that  it  can  be  executed  later 
by  the  Execute  Macro  (EM)  command.  Macro  does  not  affect  the  contents 
of  the  Text  or  Save  Buffers. 

All  characters  except  the  delimiter  are  legal  Macro  command  string 
characters,  including  single  ALTMODEs  to  terminate  text  commands. 
All  commands,  except  the  M  and  EM  commands,  are  legal  in  a  command 
string  macro. 

In  addition  to  the  OM  command,  typing  the  M  command  immediately 
followed  by  two  identical  characters  (assumed  to  be  delimiters)  and 
two  ALTMODE  characters  also  clears  the  Macro  Buffer. 

Examples : 

\ 

Clears  the  Macro  Buffer 

*fVGR0$-Cl$/$$  Stores  a  Macro  to  change  RO  to  Rl. 


NOTE 

Be  careful  to  choose  infrequently  used 
characters  as  macro  delimiters;  use  of 
frequently  used  characters  can  lead  to 
inadvertent  errors.  For  example, 

*M  GMOV  R0$  =  CRDD  Rl$  **■ 

?*N0  FILE*? 

In  this  case,  it  was  intended  that  the 
macro  be  GMOV  R0$=CADD  Rl$  but  since  the 
delimiter  character  (the  character 
following  the  M)  is  a  space,  the  space 
following  MOV  is  used  as  the  second 
delimiter,  terminating  the  macro,  EDIT 
then  returns  an  error  when  the  R0$= 
becomes  an  illegal  command  structure. 


3. 6. 5. 4  Execute  Macro  -  The  Execute  Macro  command  executes  the 
command  string  specified  in  the  last  Macro  command. 

The  form  of  the  command  iss 

nEM 

The  argument  (n)  must  be  positive.  The  macro  is  executed  n  times  and 
returns  control  to  the  next  command  in  the  original  command  string. 
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Examples : 

Executes  the  MACRO  stored  in 
the  previous  example.  An  error 
message  is  returned  when  the 
end  of  buffer  is  reached. 
(This  macro  effectively changes 
all  occurrences  of  RO  in  the 
Text  Buffer  to  Rl.) 


In  a  new  program,  inserts 
MOV  PC,Rl  then  executes  the 
command  in  the  Macro  Buffer 
twice  before  inserting  CLR 
@R2. 


3. 6. 5. 5  Edit  Version  -  The  Edit  Version  command  displays  the  version 
number  of  the  Editor  in  use  on  the  console  terminal. 

The  form  of  the  command  is : 

EV$ 


+B1000EM$$ 

?*5RClH  FAIL  IN  MRCRO*? 
* 


hc'IMOV  PC* R1$2EMICLR  ©R2** 
* 


Example : 

*EV$$ 

V02-01 

* 


3.7  THE  DISPLAY  EDITOR 

In  addition  to  all  functions  and  commands  mentioned  thus  far,  the 
Editor  has  additional  capabilities  to  allow  efficient  use  of  VT-11 
display  hardware  which  may  be  part  of  the  system  configuration  (GT40, 
GT44,  DECLAB  11/40). 

The  most  apparent  feature  is  the  ability  to  use  the  display  screen 
rather  than  the  console  terminal  as  a  window  into  the  Text  Buffer  for 
printout  of  all  textual  input  and  output.  When  all  the  features  of 
the  display  Editor  are  in  use,  the  screen  displays  text  as  shown  in 
Figure  3-1 s 


3-27 


Text  Editor 


r 


10  PRECEDING 
LINES  OF  TEXT 


CURSOR  hi 
(CURRENT  LINE)  r 


WINDOW 
\  INTO  THE 
/TEXT  BUFFER 


AND  9  FOLLOWING, 
LINES  OF  TEXT 


SEPARATION  LINE\ 


3  PRECEDING 
COMMAND  LINES 


( 


CURRENT  COMMAND^ 


LINE 


Figure  3-1 

Display  Editor  Format 


The  major  advantage  is  that  the  user  can  now  see  immediately  where  the 
pointer  is.  The  pointer  appears  between  characters  on  the  screen  as  a 
bright  blinking  L-shaped  cursor  and  can  be  detected  easily  and 
quickly.  Note  that  if  the  pointer  is  placed  between  a  carriage  return 
and  line  feed,  it  appears  in  an  inverted  position  at  the  beginning  of 
the  next  line. 

In  addition  to  displaying  the  current  line  (the  line  containing  the 
cursor) ,  the  10  lines  of  text  preceding  the  current  line  and  the  9 
lines  following  it  are  also  in  view.  Each  time  a  command  string  is 
executed  (via  a  double  ALTMODE)  this  portion  of  the  screen  is 
refreshed  so  that  it  reflects  the  results  of  the  commands  just 
performed. 

The  lower  section  of  the  screen  contains  4  lines  of  editing  commands. 
The  command  line  currently  being  entered  is  last,  preceded  by  the 
three  most  recent  command  lines.  This  section  is  separated  from  the 
text  portion  of  the  screen  by  a  horizontal  line  of  dashes.  As  new 
command  lines  are  entered,  previous  command  lines  are  scrolled  upward 
off  the  command  section  so  that  only  four  command  lines  are  ever  in 
view. 


3.7.1  Using  the  Display  Editor 

The  display  features  of  the  Editor  are  automatically  invoked  whenever 
the  system  scroller  is  in  use  and  the  user  types: 


R  EDIT 


However,  if  the  system  does  not  contain  VT-11  display  hardware,  the 
display  features  are  not  enabled. 
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Providing  that  the  system  does  contain  VT-11  display  hardware  and  that 
the  user  wishes  to  employ  the  screen  during  the  editing  session,  he 
may  activate  it  in  one  of  two  ways  (all  editing  commands  and  functions 
previously  discussed  in  this  chapter  are  valid  for  use) : 

1.  If  the  scroller  is  in  use  (i.e.,  the  GT  ON  monitor  command 
has  been  typed  prior  to  calling  the  Editor) ,  EDIT  recognizes 
this  and  automatically  continues  using  the  screen  for  display 
of  text  and  commands.  However,  it  rearranges  the  scroller  so 
that  a  "window"  into  the  Text  Buffer  appears  in  the  top 
two/thirds  of  the  screen,  while  the  bottom  third  is  used  to 
display  command  lines.  This  arrangement  is  shown  in  Figure 
3"  1  • 

The  Edit  Console  command  can  be  used  to  return  the  scroller 
to  its  normal  mode  so  that  text  and  commands  appear  as 
described  in  Chapter  2,  Section  2.7.1  (i.e.,  using  the  full 
screen  for  display  of  command  lines,  and  eliminating  the 
window) .  The  form  of  the  command  is : 

EC 


2. 


For  example; 

*BfiEC2L$$  The  second  and  third  lines  of  the 

current  buffer  are  listed  on  the  screen; 
there  is  no  window  into  the  Text  Buffer 
at  this  point. 

Subsequent  EC  commands  are  ignored  if  the  window  into  the 
Text  Buffer  is  not  being  displayed. 

To  recall  the  window,  the  Edit  Display  command  is  used: 

ED 

The  screen  is  again  arranged  as  shown  in  Figure  3-1. 

Assume  the  scroller  is  not  in  use  (i.e.,  the  GT  ON  command 
has  not  been  typed,  or  the  monitor  GT  OFF  command  has  been 
typed  prior  to  calling  the  Editor) .  When  the  user  calls  EDIT, 
an  asterisk  appears  on  the  console  terminal  as  described  in 
Section  3.1.  Using  the  ED  command  at  this  time  provides  the 
window  into  the  Text  Buffer;  however,  commands  continue  to 
be  echoed  to  the  console  terminal. 

When  ED  is  used  in  this  case,  it  must  be  the  first  command 
issued;  otherwise,  it  becomes  an  illegal  command  (since  the 
memory  used  by  the  display  buffer  and  code,  amounting  to  over 
600  words,  is  reclaimed  as  working  space).  The  display  cannot 
be  used  again  until  a  fresh  copy  of  EDIT  is  loaded. 


While  the  display  of  the  text  window  is  active,  ED 
are  ignored. 


commands 


Typing  the  EC  command  clears  the 
output  to  the  console  terminal. 


screen  and  returns  all 
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NOTE 

Under  the  Single- Job  Monitor  only,  after 
the  editing  session  is  over,  it  is 
recommended  that  the  screen  be  cleared 
by  either  typing  the  EC  command,  or 
returning  to  the  monitor  and  using  the 
monitor  INITIALIZE  command.  Failure  to 
do  this  may  cause  unpredictable  results. 


3,7.2  Setting  the  Editor  to  Immediate  Mode 

An  additional  mode  is  available  in  EDIT  to  provide  an  easier  and 
faster  degree  of  interaction  during  the  editing  session.  This  mode  is 
called  Immediate  Mode  and  combines  the  most-used  functions  of  the  Text 
and  Command  Modes — namely,  to  reposition  the  pointer  and  to  delete  and 
insert  characters. 

Immediate  Mode  may  be  used  only  when  the  VT-11  display  hardware  is 
active  and  the  Editor  is  running;  it  is  entered  by  typing  two 
ALTMODES  (only)  in  response  to  the  Command  Mode  asterisk: 

*$$ 

The  Editor  responds  by  echoing  an  exclamation  point  on  the  screen. 
The  exclamation  character  remains  on  the  screen  as  long  as  control 
remains  in  Immediate  Mode. 

Once  Immediate  Mode  has  been  entered,  only  the  commands  in  Table  3-3 
are  used.  None  of  these  commands  echoes,  but  the  text  appearing  on  the 
screen  is  constantly  refreshed  and  updated  during  the  editing  process. 
Note  that  no  EDIT  commands  other  than  those  in  Table  3-3  may  be  used 
while  control  remains  in  Immediate  Mode. 

To  return  control  to  the  display  Editor's  normal  Command  Mode  at  any 
time  while  in  Immediate  Mode,  type  a  single  ALTMODE.  The  Editor 
responds  with  an  asterisk  and  the  user  may  proceed  using  all  normal 
Editing  commands.  (Immediate  Mode  commands  typed  at  this  time  will  be 
accepted  as  Command  Mode  input  characters.)  To  return  control  to  the 
monitor  while  in  Immediate  Mode,  type  CTRL  C. 


Table  3-3 

Immediate  Mode  Commands 


Command 

Meaning 

CTRL  N 

Advance  the  pointer  (cursor)  to  the 
beginning  of  the  next  line  (equivalent 

to  A) . 

CTRL  G 

Move  the  pointer  (cursor)  to  the 

beginning  of  the  previous  line 

(equivalent  to  -A) . 
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Table  3-3  (Cont.) 
Immediate  Mode  Commands 


Command 

Meaning 

CTRL  D 

Move  the  pointer  (cursor)  forward  by  one 
character  (equivalent  to  J) , 

CTRL  V 

Move  the  pointer  (cursor)  back  by  one 
character  (equivalent  to  -J) . 

RUBOUT 

Delete  the  character  immediately 
preceding  the  pointer  (cursor) 
(equivalent  to  -D) . 

CTRL  C 

Return  control  to  the  monitor. 

ALTMODE  (one  only) 

(two) 

Return  control  to  Command  Mode. 

Direct  control  to  Immediate  Mode. 

Any  other  character 
than  those  above 

Insert  the  character  as  text  positioned 
immediately  before  the  pointer  (cursor) 
(equivalent  to  I) . 
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3.8  EDIT  EXAMPLE 

The  following  example  illustrates  the  use  of  some  of  the  EDIT  commands 
to  change  a  program  stored  on  the  device  DK.  Sections  of  the  terminal 
output  are  coded  by  letter  and  corresponding  explanations  follow  the 
example. 


R  EDIT 
*ERDK : TEST1. 

*EWDK : TESTS.  MRCff 
*R$$ 

i  TEST  PROGRAM 


B\ 


STfiRT  :  MOV  #1000,  Y.G  ; 

MOV  #MSG, £ 0  ; 

J5R  PC#  MSGTVP 
HfiLT  ; 

MSG  :  .  ASCII/IT  WORKS/ 

.  BVTE  15 
.  BVTE  12 
.  BVTE  0 


INITIALS 
POINT  R0 
PRINT 
STOP 


E  STACK 
TO  MESSAGE 


IT 


C  {*13  1J  5D*S 
f  *GF'ROGRflM$$ 
D|  *0L$$ 

H  ;  PROGRAM*] 


{ 


I  TO  TEST  SUBROUTINE  MSGTVP.  TVPES 
“THE  TEST  PROGRAM  WORKS" 

ON  THE  TELETVPE\EPVTELET\TERMINAL ** 
f  *F.  ASC 1 1 /** 

FV*8CTHE  test  program  works** 

*P.  BVTE~X 
*F.  BVTE  0*V** 

.  BVTE  0 

*1 

.  END 

*  B  /  L  *  * 

PROGRAM  TO  TEST  SUBROUTINE  MSGTVP.  TVPES 
“THE  TEST  PROGRAM  WORKS" 

ON  THE  TERMINAL 


{ 


H< 


START  : 


MSG  : 


MOV 
M  0  V 
JSR 
HALT 
.  ASC 
.  BVT 
.  BVT 
.  BVT 
.  END 


#1600#  !■  6  #*  INITIALIZE  STACK 

#MSG#tf0  ; POINT  R0  TO  MESSAGE 

PC, MSGTVP  # PRINT  IT 

#  STOP 

I  I /THE  TEST  PROGRAM  WORKS/ 

E  15 
E  12 
E  0 


♦  EX** 
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A  The  EDIT  program  is  called  and  prints  an  *.  The  input  file  is 

TEST1 . MAC ;  the  output  file  is  TEST2 . MAC  and  the  first  page  of 

input  is  read. 

B  The  buffer  contents  are  listed. 

C  Be  sure  the  pointer  is  at  the  beginning  of  the  buffer.  Advance 

pointer  one  character  (past  the  ;)  and  delete  the  "TEST  ". 

D  Position  pointer  after  PROGRAM  and  verify  the  position  by  listing 
up  to  the  pointer. 

E  Insert  text.  RUBOUT  used  to  correct  typing  error. 

F  Search  for  .ASCII/  and  change  "IT  WORKS"  to  "THE  TEST  PROGRAM 

WORKS". 

G  CTRL  X  typed  to  cancel  P  command.  Search  for  ".BYTE  0"  and 

verify  location  of  pointer  with  V  command. 

H  Insert  text.  Return  pointer  to  beginning  of  buffer  and  li*st 

entire  contents  of  buffer. 

I  Close  input  and  output  files  after  copying  the  current  text 

buffer  as  well  as  the  rest  of  input  file  into  output  file.  EDIT 
returns  control  to  the  monitor. 


3.9  EDIT  ERROR  MESSAGES 

The  Editor  prints  an  error  message  whenever  one  of  the  error 
conditions  listed  next  occurs.  Prior  to  executing  any  commands,  the 
Editor  first  scans  the  entire  command  string  for  errors  in  command 
format  (illegal  arguments,  illegal  combinations  of  commands,  etc.).  If 
an  error  of  this  type  is  found,  an  error  message  of  the  form: 

7ERROR  MSG? 

is  printed  and  no  commands  are  executed.  The  user  must  retype  the 
command. 

If  the  command  string  is  syntactically  correct,  execution  is  started. 
Execution  errors  are  still  possible,  however  (buffer  overflow,  I/O 
errors,  etc.),  and  if  such  an  error  occurs,  a  message  of  the  form: 

?*ERR0R  MSG*? 

is  printed.  In  this  case,  all  commands  preceding  the  one  in  error  are 
executed,  while  the  command  in  error  and  those  following  are  not 
executed.  Most  errors  will  generally  be  of  the  syntax  type  and  can  be 
corrected  before  execution. 
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When  an  error  occurs  during  execution  of  a  Macro,  the  message  format 

IS  ! 

?message  IN  MACRO? 
or 

?*message  IN  MACRO*? 
depending  on  when  it  is  detected. 


Message 

Explanation 

*CB  ALMOST  PULL* 

The  command  currently  being  entered  is  within 
10  characters  of  exceeding  the  space 
available  in  the  Command  Buffer. 

?CB  FULL? 

Command  exceeds  the  space  allowed  for  a 
command  string  in  the  Command  Buffer. 

?ILL  ARG? 

The  argument  specified  is  illegal  for  the 
command  used.  A  negative  argument  was 
specified  where  a  positive  one  was  expected 
or  argument  exceeds  the  range  +  or  -  16,383. 

?ILL  CMD? 

EDIT  does  not  recognize  the  command 
specified;  ED  was  not  the  first  command 
issued  when  used  to  activate  the  display 
hardware. 

?ILL  MAC? 

Delimiters  were  improperly  used,  or  an 
attempt  was  made  to  enter  an  M  command  during 
execution  of  a  Macro  or  an  EM  command  while 
an  EM  was  in  progress. 

?*DIR  FULL*? 

No  room  in  device  directory  for  output  file. 

?*EOF*? 

Attempted  a  Read,  Next  or  file  searching 
command  and  no  data  was  available. 

?*FILE  FULL*? 

Available  space  for  an  output  file  is  full. 
Type  a  CTRL  C  and  the  CLOSE  monitor  command 
to  save  the  data  already  written. 

?*FILE  NOT  FND*? 

Attempted  to  open  a  nonexisting  file  for 
editing. 

?*HDW  ERR*? 

A  hardware  error  occurred  during  I/O.  May  be 
caused  by  WRITE  LOCKed  device.  Try  again. 

?*ILL  DEV*? 

Attempted  to  open  a  file  on  an  illegal 
device,  or  attempted  to  use  display  hardware 
when  none  was  available  (it  may  be  in  use  by 
the  other  job) . 
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Message 

Explanation 

?*ILL  NAME*? 

File  name  specified  in  EB,  EW,  or  ER  is 
illegal. 

?*N0  FILE*? 

Attempted  to  read  or  write  when  no  file  is 
open. 

?*N0  ROOM*? 

Attempted  to  Insert ,  Save,  Unsave,  Read, 
Next,  Change  or  Exchange  when  there  was  not 
enough  room  in  the  appropriate  buffer. 
Delete  unwanted  buffers  to  create  more  room 
or  write  text  to  the  output  file. 

?*N0  TEXT*? 

Attempted  to  call  in  text  from  the  Save 
Buffer  when  there  was  no  text  available. 

?*SRCH  FAIL*? 

The  text  string  specified  in  a  Get,  Find  or 
Position  command  was  not  found  in  the 
available  data. 

?  H  <  > " ERR? 

Iteration  brackets  are  nested  too  deeply  or 
used  illegally  or  brackets  are  not  matched. 
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PERIPHERAL  INTERCHANGE  PROGRAM  (PIP) 


The  Peripheral  Interchange  Program  (PIP)  is  the  file  transfer  and 
maintenance  utility  for  RT-11.  PIP  is  used  to  transfer  files  between 
any  of  the  RT-11  devices  (listed  in  Table  2-2)  ,  merge  and  delete  files 
from  these  devices,  and  list,  zero,  and  compress  device  directories. 


4.1  CALLING  AND  USING  PIP 
To  call  PIP  from  the  system  device  types 
R  PIP 

in  response  to  the  dot  printed  by  the  Keyboard  Monitor.  The  Command 
String  Interpreter  prints  an  asterisk  at  the  left  margin  of  the 
terminal  and  waits  to  receive  a  line  of  filenames  and  command 
switches.  PIP  accepts  up  to  six  input  filenames  and  three  output 
filenames;  command  switches  are  generally  placed  at  the  end  of  the 
command  string  but  may  follow  any  filename  in  the  string.  There  is  no 
limit  to  the  number  of  switches  which  may  be  indicated  in  a  command 
line,  as  long  as  only  one  operation  (insertion,  deletion,  etc.)  is 
represented. 

Since  PIP  performs  file  transfers  for  all  RT-11  data  formats  (ASCII, 
object,  and  image)  there  are  no  assumed  extensions  for  either  input  or 
output  files;  all  extensions,  where  present,  must  be  explicitly 
specified. 

Following  completion  of  a  PIP  operation,  the  Command  String 
Interpreter  prints  an  asterisk  at  the  left  margin  of  the  teleprinter 
and  waits  for  another  PIP  command  line.  Typing  CTRL  C  at  any  time 
returns  control  to  the  Keyboard  Monitor.  To  restart  PIP,  type  R  PIP 
or  the  REENTER  command  in  response  to  the  monitor's  dot. 


4.1.1  Using  the  "Wild  Card"  Construction 

PIP  follows  the  standard  file  specification  syntax  explained  in 
Section  2.5.  (Chapter  2)  with  one  exception:  the  asterisk  character 
can  be  used  in  a  command  string  to  represent  filenames  or  extensions. 
The  asterisk  (called  the  "wild  card")  in  a  file  specification  means 
"all".  For  instance,  "".MAC"  means  all  files  with  the  extension  .MAC. 
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regardless  of  filename.  "FORTN.*"  means  all  files  with  the  filename 
FORTN  regardless  of  extension.  "*.*"  means  all  files,  regardless  of 
name  or  extension. 

The  wild  card  character  is  legal  in  the  following  cases  only  (switches 
are  explained  in  the  next  section) : 

1.  Input  file  specification  for  the  copy  and  multiple  copy 
operations  (i.e.,  no  switch,  /I,  /B,  and  /A). 

2.  File  specification  for  the  delete  operation  (/D) . 

3.  Input  and  output  file  specifications  for  the  rename  operation 

(/R) . 

4.  Input  and  output  file  specifications  for  the  multiple  copy 
operation  (/X) . 

5.  Input  file  specifications  for  the  directory  list  operations 
(/L,  /E,  /F). 

Operations  on  files  implied  by  the  wild  card  asterisk  are  performed  in 
the  order  in  which  the  files  appear  in  the  directory.  System  files 
with  the  extension  .SYS  and  files  with  bad  blocks  and  the  extension 
.BAD  are  ignored  when  the  wild  card  character  is  used  unless  the  /Y 
switch  is  specified. 

Examples : 


**.  BftK/D 


♦  ♦ .  T  5  T  -  * .  B  ft  K  <'  R 


*RK1 !***/X/Y^*** 


%% ♦ MAC  *  # ♦ OB J/L 


Causes  all  files  with  the  extension  .BAK 
(regardless  of  their  filenames)  to  be 
deleted  from  the  device  DK. 

Renames  all  files  with  a  .BAK  extension 
(regardless  of  filenames)  so  that  these 
files  now  have  a  .TST  extension 
(maintaining  the  same  filenames) . 

Transfers  all  files,  including  system 
files,  (regardless  of  filename  or 
extension)  from  device  DK  to  device  RKl. 

Lists  all  files  with  .MAC  and  .OBJ 
extensions . 


4.2  PIP  SWITCHES 

The  various  operations  which  can  be  performed  by  PIP  are  summarized  in 
Table  4-1.  If  no  switch  is  specified,  PIP  assumes  the  operation  is  a 
file  transfer  in  image  (/I)  mode.  Detailed  explanations  of  the 
switches  follow  the  table. 
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Table  4-1 
PIP  Switches 


Switch  ! 

Section 

Explanation 

/A 

4.2.2 

Copies  file(s)  in  ASCII  mode;  ignores  nulls  and 

rubouts;  converts  to  7-bit  ASCII. 

/B 

4.2.2 

Copies  files  in  formatted  binary  mode. 

/c 

4.2.2 

Used  in  conjunction  with  another  switch;  causes 
only  files  with  current  date  (as  designated  using 
the  monitor  DATE  command)  to  be  included  in  the 
specified  operation. 

/D 

4.2.4 

Deletes  file(s)  from  specified  device. 

/E 

4.2.6 

Lists  the  device  directory  including  unused  spaces 
and  their  sizes.  An  empty  space  on  a  cassette  or 
magtape  directory  represents  a  deleted  file. 
Sequence  numbers  are  listed  for  cassettes. 

/F 

4.2.6 

Prints  a  short  directory  (filenames  only)  of  the 
specified  device. 

/G 

4.2.2 

Ignores  any  input  errors  which  occur  during  a  file 
transfer  and  continues  copying. 

/I  or  no 
switch 

4.2.2 

Copies  file(s)  in  image  mode  (byte  by  byte).  This 
is  the  default  switch. 

/K 

4.2.12 

Scans  the  specified  device  and  types  the  absolute 
block  numbers  (in  octal)  of  any  bad  blocks  on  the 
device . 

A 

4.2.6 

Lists  the  directory  of  the  specified  device, 
including  the  number  of  files,  their  dates,  and 
the  number  of  blocks  used  by  each  file.  Sequence 
numbers  are  listed  for  cassettes. 

/Msn 

4.2.1 

Used  when  I/O  transfers  involve  either  cassette  or 
magtape,  n  represents  the  numeric  position  of  the 
file  to  be  accessed  in  relation  to  the  physical 
position  of  the  cassette  or  magtape  on  the  drive. 

If  n  is  positive,  the  tape  spaces  forward  from  its 
current  position  until  either  the  filename  or  the 
nth  file  is  found;  if  n  is  negative,  the  tape  is 
rewound  first,  and  then  it  spaces  forward  until 
either  the  filename  or  the  nth  file  is  found.  If 
n  is  0  (or  not  indicated)  the  tape  is  rewound  and 
searched  for  the  filename.  For  wild  card 
operations,  specification  of  /M  with  a  positive 
argument  will  prevent  the  tape  from  rewinding 
between  each  file  involved  in  the  operation. 

/N:n 

4.2.7 

Used  with  /Z  to  specify  the  number  of  directory 
segments  (n)  to  allocate  to  the  directory. 

/o 

4.2.10 

Bootstraps  the  specified  device  (DTO,  RKn,  or  RF 
only) . 
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Table  4-1  (Cont.) 


Switch 

Section 

Explanation 

/Q 

4.2.2 

When  used  in  conjunction  with  another  PIP 

operation,  causes  PIP  to  type  each  filename  which 
is  eligible  for  a  wild  card  operation  and  to  ask 
for  a  confirmation  of  its  inclusion  in  the 
operation.  Typing  a  "Y"  causes  the  named  file  to 
be  included  in  the  operation;  typing  anything 
else  excludes  the  file.  The  command  line  is  not 
processed  until  the  user  has  confirmed  each  file 
in  the  operation. 

/R 

4.2.5 

Renames  the  specified  file. 

/s 

4.2.8 

Compresses  the  files  on  the  specified  directory 
device  so  that  free  blocks  are  combined  into  one 
area. 

/T 

4.2.4 

Extends  number  of  blocks  allocated  for  a  file. 

/u 

4.2.9 

Copies  the  bootstrap  from  the  specified  file  into 
absolute  blocks  0  and  2  of  the  specified  device. 

A 

4.2.11 

Types  the  version  number  of  the  PIP  program  beinq 
used. 

A 

4.2.6 

Includes  the  ab solute  starting  block  and  any  extra 
directory  words  in  the  directory  listing  for  each 
file  on  the  device  (numbers  in  octal) .  Used  with 
/F,  /L,  or  /E. 

/X 

4.2.3 

Copies  files  individually  (without  concatenation) . 

n 

4.2.2 

Causes  system  files  and  .BAD  files  to  be  operated 
on  by  the  command  specified.  Attempted 
modifications  or  deletions  of  .SYS  or  .BAD  files 
without  /Y  are  not  done  and  cause  the  message  ?N0 
SYS  ACTION?  to  be  printed. 

/Z:n 

4.2.7 

Zeroes  (initializes)  the  directory  of  the 
specified  device;  n  is  used  to  allocate  extra 
words  per  directory  entry.  When  used  with  /N,  the 
number  of  directory  segments  for  entries  may  be 
specified.  When  used  with  cassette,  /Z  writes  a 
sentinel  file  at  the  beginning  of  the  tape;  with 
magtape,  /Z  writes  a  volume  label  followed  by  a 
dummy  file  followed  by  double  tape  marks 
indicating  logical  end-of-tape. 

4.2.1  Operations  Involving  Magtape  or  Cassette 

PIP  operations  involving  cassette  and  magtape  devices  are  handled 
somewhat  differently  than  other  RT-11  devices,  because  of  the 
sequential  nature  of  these  devices.  The  last  file  on  a  cassette  or 
magtape  (the  logical  end-of-tape)  is  specially  formatted  so  that  it 
marks  the  end  of  current  data  and  indicates  where  new  data  may  begin 
(double  end-of-file  for  magtape,  sentinel  file  or  physical  end-of-tape 
for  cassette) .  Therefore,  operations  which  designate  specific  block 
lengths  (such  as  /T  and  /N)  are  meaningless,  and  unused  spaces  on  the 
tape  (resulting  from  file  deletions)  cannot  be  filled. 
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PIP  operations  which  are  legal  using  cassette  and  magtape  include  the 
following:  / A ,  /B,  /D,  /E,  /F,  /G,  /I,  /L,  /M,  /Q,  /V,  /W,  /X,  /Y, 

and  /Z.  Usually  the  device  (CT  or  MT)  is  rewound  each  time  an 

operation  is  performed.  Since  there  is  no  inclusive  directory  at  the 
beginning  of  the  tape  the  only  way  to  access  a  file  is  to  search  the 

tape  from  the  beginning  until  it  is  found.  However ,  the  /M:n  switch 

is  available  for  situations  where  it  is  not  necessary  or  desirable  to 
rewind  the  tape  before  each  operation.  If  the  argument  (n)  is 
positive ,  the  operation  indicated  will  not  rewind  the  tape  first,  but 
will  space  forward  until  it  finds  either  the  nth  file,  the  filename 
indicated  in  the  command  line,  or  the  logical  end-of-tape,  whichever 

occurs  first.  If  the  argument  is  negative,  the  cassette  or  magtape 

will  be  rewound  first  and  then  spaced  forward  until  the  filename  (or 
nth  file,  or  logical  end-of-tape)  is  found.  Thus: 

/M:l  means  suppress  rewind,  begin  operation  at 

current  position. 

/M:-l  means  rewind  tape  and  access  the  first  file 

on  it. 


Remember  that  when  /M:n  is  used,  n  is  interpreted  as  an  octal  number. 
/Min  must  be  used  if  it  is  intended  that  n  represent  a  decimal  number. 

For  example,  assume  the  directory  of  a  cassette  on  unit  1  is: 

17-JUL-74 

FILE  .1  0  5-MAY-74 

FILE  .2  0  5-MAY-74 

FILE  .3  1  13-MAY-74 

FILE  • A  1  28-JUN-74 

FILE  .5  0  17-JUL-74 

5  FILES*  2  BLOCKS 
* 

and  the  last  PIP  operation  involved  FILE. 4,  leaving  the  cassette 
positioned  at  the  end  of  FILE. 4.  To  access  FILE. 2,  the  next  operation 
(for  example,  deleting  FILE. 2)  could  use  the  /M  construction: 

*CT1 : DUM/M : -2/D 

In  this  case,  the  cassette  rewinds  first,  then  spaces  forward  from  its 
current  position  to  the  second  file  in  sequence  and  deletes  it.  (In  a 
delete  operation,  the  dummy  filename  is  necessary;  otherwise,  a 
non- file  structured  delete  is  performed  and  the  tape  is  zeroed.  See 
Section  4.2.4). 

Another  useful  application  of  the  /M  switch  involves  a  case  where  a 
number  of  files  are  to  be  created  on  a  magtape  or  cassette.  Using  the 
construction: 

*/tf=FILE.  1,  FILE.  2.  .  .  /M :  1000 

prevents  a  rewind  from  occurring  before  each  new  file  is  created  on 
the  tape.  Normal  operation  (when  creating  a  new  file  on  magtape  or 
cassette)  is  to  rewind,  then  search  the  tape  for  the  logical  end.  If 
a  file  with  the  same  name  as  the  one  being  created  is  encountered,  it 
is  deleted  and  the  new  file  is  opened  at  the  logical  end  of  the  tape. 
The  /M:1000  command  first  causes  the  tape  to  space  forward  until  it 
reaches  the  logical  end-of-tape,  (assuming  less  than  1000  (octal) 
files  on  the  tape) ,  at  which  point  the  next  file  is  entered,  and  so 
on.  If  the  tape  were  already  positioned  at  the  end  of  the  tape,  an 
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/M:l  would  suffice  to  cause  the  new  file  to  be  written  there.  Note 
that  creation  of  a  new  file  with  the  /M  switch  can  result  in  several 
files  with  the  same  name  on  the  same  tape;  those  files  occurring 
before  the  tape  position  are  not  searched  for  duplication  prior  to  the 
creation  of  the  new  file, 

RT-11  magtapes  sometimes  contain  a  dummy  file  at  the  beginning  of  the 
tape,  which  is  written  when  the  tape  is  initialized  with  the  /Z 
switch.  This  file  shows  up  in  extended  directories  (/E)  as  an 
< UNUSED >  entry  in  the  first  file  position.  Deleted  files  on  magtape 
or  cassette  do  not  show  up  in  /F  or  /L  directory  listings,  but  must 
always  be  considered  when  the  /Msn  switch  is  used.  Care  must  always 
be  taken  to  use  a  /E  directory  when  counting  file  position  prior  to 
using  that  position  as  an  /M:n  argument;  <UNUSED>  files  must  be 
counted  as  files  on  the  tape. 


For  examples 


.  R  PIP 
*MT0 : /E 
ll-SEP-74 

<  UNUSED  > 

fi  .  MRC 

B  .  MRC 

<  UNUSED  > 

D  .  MAC 

3  FILES,  57 

*MT0.VL 
ll-SEP-74 
fi  .  MfiC 

B  .  MfiC 

D  .  MfiC 

3  FILES,  57 


0 

40  ll-SEP-74 
15  ll-SEP-74 
2 

2  ll-SEP-74 
BLOCKS 


40  ll-SEP-74 
15  ll-SEP-74 
2  ll-SEP-74 
BLOCKS 


Extended  directory:  shows 
absolute  file  positions. 


Normal  directory;  does 
not  accurately  display 
file  positions. 


If  the  user  wished  to  access  file  A. MAC  on  the  magtape  in  the  example 
above,  /Ms-2  must  be  used  (/Ms-1  would  access  the  first  empty  file). 
Likewise,  B.MAC  is  accessed  with  /M:-3.  Rewind  can  also  be  suppressed 
for  cassette  and  magtape  as  input  devices  by  specifying  a  very  large 
number  in  conjunction  with  wild  card  transfers  from  magtape  or 
cassette. 


+  * .  * = M  T  0  :  * .  *  /  M  :  2  0  0 0 
?0UT  FIL? 


This  transfers  all  files  from  MTOs  to  DKs  without  rewinding  between 
each  file.  The  argument  2000  is  an  arbitrarily  large  number;  any 
number  larger  than  the  actual  number  of  files  on  the  tape  will 
stiff  ice.  An  error  message  indicates  when  all  files  have  been 
transferred. 

The  most  common  method  for  spacing  to  the  end  of  the  tape  iss 

*DUMMV=MT0 : DUMMV/M : 2000 
?F I L  NOT  FND? 

where  DUMMY  is  a  file  name  which  does  not  exist  on  the  tape.  Note 
that  an  error  message  is  printed  when  the  end  of  the  tape  is  reached. 
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Directory  listings  of  magtapes  include  the  length  of  each  file  in 
256 (decimal)  word  blocks.  In  cassette  directories,  however,  sequence 
numbers  rather  than  block  numbers  are  printed.  Sequence  numbers 
indicate  the  sequential  ordering  of  a  file  in  cases  where  it  has  been 
continued  on  more  than  one  cassette.  In  the  example  cassette 
directory  listing  (at  the  beginning  of  this  section) ,  the  numbers  in 
the  middle  column  represent  sequence  numbers;  both  FILE. 3  and  FILE. 4 
are  the  second  segments  of  continued  files.  All  files  on  cassette  are 
initially  assigned  a  sequence  number  of  0.  The  sequence  number  is 
automatically  updated  whenever  the  file  must  be  continued  as  a  result 
of  a  full  cassette. 

During  I/O  transfer  operations  involving  cassette,  if  the  cassette  is 
full  before  the  transfer  has  finished,  the  message: 

CTn:  PUSH  REWIND  OR  MOUNT  NEW  VOLUME 

is  printed;  n  represents  the  number  of  the  drive  (0  or  1)  on  which 
the  current  cassette  is  mounted.  If  the  cassette  rewind  button  is 
subsequently  pushed,  an  error  message  is  typed  (IN  or  OUT  ERR)  and  the 
tape  is  rewound. 

To  continue  an  output  operation,  mount  a  new  cassette  (which  has  been 
properly  formatted  as  described  in  Section  4.2.7)  on  the  same  drive. 
The  new  cassette  is  rewound  automatically  and  a  file  is  opened  on  it 
under  the  same  name  and  extension;  the  sequence  number  in  its 
directory  is  updated  to  reflect  the  continuation,  and  the  transfer 
continues . 

If  the  message  occurs  during  an  input  operation,  mount  the  cassette 
containing  the  continued  portion  of  the  file  on  the  drive;  the 
cassette  is  rewound  first.  PIP  then  looks  for  a  file  with  the  same 
name  and  extension  and  the  proper  sequence  number  and  continues  the 
input  operation.  The  message  is  repeated  if  the  next  segment  is  not 
found. 

For  example: 

*CT0  .  FILE.  AGA=DT  1 :  fiSC.  MAC/  DK  :  BALOR.  MAC /A 
CT0 :  PUSH  REWIND  OR  MOUNT  NEW  VOLUME 

This  copies  in  ASCII  mode  the  file  ASC.MAC  from  DECtape  1  and 
BALOR.MAC  from  device  DK  and  combines  them  under  the  name  FILE.AGA  on 
CTO.  The  cassette  runs  out  of  room  and  requests  that  a  new  one  be 
mounted.  The  operation  continues  automatically  when  the  second 
cassette  has  been  mounted. 

A  directory  of  the  second  cassette  in  the  above  operation  is  next 
requested;  note  that  the  sequence  number  of  FILE.AGA  is  1,  signifying 
it  is  the  second  part  of  a  continued  file. 

*CT0: /L 
23-MAY- 7 4 

TRA  .BIN  0  16-FEB-74 

FILE  .AGA  I  23-MAY-74 

2  FILES,  I  BLOCKS 
* 

(The  number  of  blocks  in  a  cassette  directory  simply  represents  the 
total  of  sequence  numbers  in  the  directory.) 

Any  cassette  mounted  in  response  to  a  continuation  message  MUST  have 
been  previously  initialized  at  some  time  as  described  in  Section 
4.2.7. 
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If  a  full  cassette  is  mounted  or  an  attempt  is  made  to  access  some 
file  on  it  that  does  not  exist,  the  continuation  message  re-occurs. 
The  operation  may  be  continued  by  mounting  another  cassette. 

Note  that  if  an  attempt  is  made  to  access  a  file  which  has  a  non-zero 
sequence  number  (during  some  operation  which  is  not  a  continuation  of 
an  operation) ,  the  file  will  not  be  found. 

If  the  end  of  a  tape  is  reached  during  a  magtape  I/O  operation,  an  IN 
or  OUT  ERR  message  is  printed.  Continuation  on  another  magtape  is  not 
allowed  and  the  operation  must  be  repeated  using  a  different  magtape. 

If  CTRL  C  is  typed  during  any  output  operation  to  cassette  or  magtape, 
an  end-of-tape  or  sentinel  file  is  not  written  on  the  tape  first. 
Consequently,  no  future  enters  may  occur  to  the  tape  unless  one  of  two 
recovery  procedures  is  followed: 

1.  Transfer  all  good  files  from  the  bad  tape  to  another  tape  and 
zero  the  bad  tape  in  the  following  manner: 

*devl : * . */X=devO : f i lei , f ile2 , . . . f ilen/M: 10  0  0 
*devO:/Z 

devO : /Z  ARE  YOU  SURE  ? 

This  causes  a  logical  end-of-tape  to  be  written  onto  the  bad 
tape  and  makes  it  again  available  for  use. 

2.  Determine  the  sequential  number  of  the  file  which  was 
interrupted  and  use  the  /M  construction  to  enter  a 
replacement  file  (either  a  new  file  or  a  dummy  file). 
Assuming  the  bad  file  is  the  4th  file  on  the  tape,  use  a 
command  line  of  this  construction: 

*de vO : f i le . new=f i le . dum/M : - 4 

A  logical  end-of-tape  now  exists  on  the  tape,  making  it 
available  for  use. 

Since  magtapes  and  cassettes  are  not  random  access  devices,  each  unit 
cam  have  only  one  file  accessed  at  a  time.  Avoid  PIP  command  strings 
which  specify  the  same  unit  number  for  both  input  amd  output,  since  a 
loss  of  information  cam  occur.  For  example: 

*CT0:  FILE1  .MAOCT0:  FILE1  .MAC 
?FI L  NOT  FND? 

* 

The  result  of  this  operation  is  to  delete  FILE 1. MAC  before  the  error 
message  is  printed.  The  filename  is  not  deleted  from  the  directory, 
however. 

Recovery  procedures  for  errors  caused  by  bad  tapes  are  described  in 
RT-11  SOFTWARE  SUPPORT  MANUAL  (DEC-ll-ORPGA-B-D) . 
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4.2.2  Copy  Operations 

A  command  line  without  a  switch  causes  files  to  be  copied  onto  the 
destination  device  in  image  mode  (byte  by  byte) .  This  operation  is 
used  to  transfer  memory  image  (save  format)  files  and  any  files  other 
than  ASCII  or  formatted  binary.  For  example: 

*RBC<XVZ  Makes  a  copy  of  the  file  named  XYZ  on 

device  DK  and  assigns  the  name  ABC. 
(Both  files  exist  on  device  DK  following 
the  operation) . 

*  S  V  :  B  fi  C  K .  B I N = P  R  :  / 1  Copies  a  tape  from  the  papertape  reader 

to  the  system  device  in  image  mode  and 
assigns  it  the  name  BACK.BIN. 

The  /A  switch  is  used  to  copy  file(s)  in  ASCII  mode  as  follows: 

*DT1:F1<F2/R  Copies  F2  from  device  DK  onto  device  DTI 

in  ASCII  mode  and  assigns  the  name  FI. 

Nulls  and  rubouts  are  ignored  in  an  ASCII  mode  file  transfer. 

The  /B  switch  is  used  to  transfer  formatted  binary  files.  The 
formatted  binary  copy  switch  should  be  used  for  .OBJ  files  produced  by 
the  assembler  or  FORTRAN  and  for  .LDA  files  produced  by  the  Linker. 
For  example: 

*DK  :  FILE.  OBJ<F'R  :  /B  Transfers  a  formatted  binary  file  from 

the  papertape  reader  to  device  DK  and 
assigns  the  name  FILE. OBJ. 

When  performing  formatted  binary  transfers,  PIP  verifies  checksums  and 
prints  the  message  ?CHK  SUM?  if  a  checksum  error  occurs. 

To  combine  more  than  one  file  into  a  single  file,  use  the  following 
format : 


*DK  :  RfKDTl :  BB.  CC,  DD/1 

Transfers  files  BB,  CC  and  DD  to  device 
DK  as  one  file  and  assigns  this  file  the 
name  AA. 

*DT3  :  MERGE=DT2  :  FIIE2,  FILE3/R 

Merges  ASCII  files  FILE2  and  FILE3  on 
DT2  into  one  ASCII  file  named  MERGE  on 
device  DT3. 

Errors  which  occur  during  the  copy  operation  (such  as  a  parity  error) 
cause  PIP  to  output  an  error  message  and  return  for  another  command 
string. 

The  /G  switch  is  used  to  copy  files  but  ignore  all  input  errors.  For 
example : 

*RBC<CDT1:TGP/G  Copies  file  TOP  in  image  mode  from 

device  DTI  to  device  DK  and  assigns  the 
name  ABC.  Any  errors  during  the  copy 
operation  are  ignored. 


4-9 


Peripheral  Interchange  Program 


*DT2  :  C 0 M B < D T 1  :  F  I,  F2,'ft/G 

Copies  files  FI  and  F2  in  ASCII  mode 
from  device  DTI  to  device  DT2  as  one 
file  with  the  name  COMB.  Ignores  input 
errors . 

The  wild  card  construction  may  be  used  for  input  file  specifications 
during  copy  operations •  Be  sure  to  use  the  /Y  switch  if  system  files 
(.SYS)  are  to  be  copied.  For  example: 

*DT1 JPROGIOK.MAC  Copies,  in  image  mode,  all  files  with  a 

.MAC  extension  from  device  DK  to  device 
DTI  and  combines  them  under  the  name 
PR0G1. 

**.*=BT3:*.*/G/Y/X  Copies  to  device  DK,  in  image  mode,  all 

files  (including  .SYS  files)  from  device 
DT3;  ignores  any  input  errors. 

If  only  files  with  the  current  date  are  to  be  copied  (using  the  wild 
card  construction) ,  the  /C  switch  must  also  be  used  in  the  command 
line .  For  example : 


*DT2  :  NN3=ITEM1.  */C,  ITEM2/FI 

Copies,  in  ASCII  mode,  all  files  having 
the  filename  ITEM1  and  the  current  date, 
(the  date  entered  using  the  monitor  DATE 
command)  and  copies  ITEM2  (regardless  of 
its  date)  from  device  DK  to  device  DT2 
and  combines  them  under  the  name  NN3. 

*DT3 :*.*=*.  */C/X  Copies  all  files  with  the  current  date 

from  DK  to  DT3.  Note  that  commands  of 
this  nature  are  an  efficient  way  to 
backup  all  new  files  after  a  session  at 
the  computer. 

The  /Q  switch  is  used  in  conjunction  with  another  PIP  operation  and 
the  wild  card  construction  to  list  all  files  and  allow  the  user  the 
opportunity  to  confirm  individually  which  of  these  files  should  be 
processed  during  the  wild  card  expansion.  Typing  a  "Y"  causes  the 
named  file  to  be  processed;  typing  anything  else  excludes  the  file. 
For  example: 

**-.OBJ<DTl  !*.OBJ/G/X  ,  w 

■ttrst  .OB  JVY  Copies  the  files  FIRST. OBJ  and 

GETR  .OBJ?  CARJ.OBJ  to  the  disk  in 

BORB  .OBJ?  image  mode  from  DECtape  1 

CARJ  , OB j?Y  and  ignores  the  others. 

The  file  allocation  scheme  for  RT-11  normally  allows  half  the  entire 
largest  available  space  or  the  second  largest  space,  or  a  maximum  size 
(a  constant  which  may  be  patched  in  the  RT-11  monitor;  see  GETTING 
STARTED  WITH  RT-11,  DEC-11-0RCPA-D-D) ,  whichever  is  largest,  for  a  new 
file.  The  user  can,  using  the  [n]  construction  explained  in  Chapter 
2,  force  RT-11  to  allow  the  entire  largest  possible  space  by  setting 
n**177777.  If  n  is  set  equal  to  any  other  value  (other  than  0  which  is 
default  and  gives  the  normal  allocation  described  first  above) ,  that 
size  will  be  allocated  for  the  file. 
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Therefore,  assume  that  the  directory  for  a  given  device  shows  a  free 
area  of  200  blocks  and  that  PIP  returns  an  ?OUT  ER?  message  when  a 
transfer  is  attempted  to  that  device  with  a  file  which  is  longer  than 
100  blocks  but  less  than  200  blocks.  Transfers  in  this  situation  can 
be  accomplished  in  either  of  two  ways: 

1.  Use  the  [n]  construction  on  the  output  file  to  specify  the 
desired  length  (refer  to  Chapter  2,  Section  2.5  for  an 
explanation  of  the  [n]  construction) . 

2.  Use  the  /X  switch  during  the  transfer  to  force  PIP  to 
allocate  the  correct  number  of  blocks  for  the  output  file. 
This  procedure  will  operate  correctly  if  the  input  device  is 
OECtape  or  disk. 

For  example,  assume  that  file  A  is  150  blocks  long  and  that  a 
directory  listing  shows  that  there  is  a  200  block  <unused>  space  on 
DTI: 

.  R  PIP 

*DT1 : fi  =  fl 

?0UT  ER?  File  longer  than  100  blocks. 

*DT1 :  RC 150  ]=fi 

or  Either  command  causes  a  correct 

*DT1 : R=fi/X  transfer. 


4.2.3  Multiple  Copy  Operations 

The  /X  switch  allows  the  transfer  of  several  files  at  a  time  onto  the 
destination  device  as  individual  files.  The  /A,  /G,  /C,  /Q,  /B  and  A 
switches  can  be  used  with  /X.  If  /X  is  not  indicated,  all  output  files 
but  the  first  will  be  ignored. 


Examples : 

*  F I LE1 1 F I L E 2 » F I L  E  3 < D T 1 ♦ F I L E  A  v F I L E B * F I L  E C / X 

Copies,  in  image  mode,  FILEA,  FILEB  and 
FILEC  from  device  DTI  to  device  DK  as 
separate  files  called  FILE1,  FILE2  and 
FILE3,  respectively. 

*DT2 : FI.  *=F2. #/X  Copies,  in  image  mode,  all  files  named 
?N0  SVS  RCTI0N?  F2  (except  files  with  .SYS  or  .BAD 

*  extensions)  from  device  DK  to  device 

DT2.  Each  file  is  assigned  the  filename 
FI  but  retains  its  original  extension. 


#DT1  $  #  ♦  * — T 2 ♦  # . #/X  Copies,  in  image  mode,  all  files  on 
?NC)  SYS  ACTION?  device  DT2  to  device  DTI  (except  files 

with  .SYS  or  .BAD  extensions) ;  the  files 
are  copied  separately  and  retain  the 
same  names  and  extensions. 


*DT1  :  FILE1, F I LE2<F I LEfi.  */R/G/X 

This  command  line  assumes  there  are  two 
files  with  the  filename  FILEA  (and  any 
extension  excluding  .SYS  or  .BAD 
extensions)  and  copies  these  files  in 
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ASCII  mode  to  device  DTI.  The  files  are 
transf erred  in  the  order  they  are  found 
in  the  directory;  the  first  file  found 
is  copied  and  assigned  the  name  FILEl, 
and  the  second  is  assigned  FILE2.  If 
there  is  a  third,  it  is  ignored  and  a 
fourth  causes  an  ?OUT  FIL?  error. 


*DT0  SVS  =  *.  SVS/X/V 

Copies  all  system  files  from  device  DK 
to  device  DTO. 

File  transfers  performed  via  normal  operations  place  the  new  file  in 
the  largest  available  area  on  the  disk.  The  /X  switch,  however, 
places  the  copied  files  in  the  first  free  place  large  enough  to 
accommodate  it.  Therefore,  the  /X  switch  should  be  used  whenever 
possible  (i.e.,  when  no  concatenation  is  desired)  as  an  aid  to 
reducing  disk  fragmentation. 

♦  ft = B 

and 

perform  the  same  operation;  however,  using  the  second  construction 
whenever  possible  increases  the  system  disk-usage  efficiency. 

For  example,  assume  the  directory  of  DTI  is: 


9  -  M  ft  V  -  7  4 
MONITR.  SVS 

22 

5-MftV-74 

<  UNUSED  > 

2 

PR  .  SVS 

2 

5-MRV-74 

<  UNUSED  > 

528 

2  FILES.  34  BLOCKS 
520  FREE  BLOCKS 

To  copy  the  file  PP.SYS  (2  blocks  long)  from  DK  to  DTI,  the  command: 


*DT1 :  PP.  S V S  =  P F' .  SVS/V 


can  be  entered,  and  the  new  directory  iss 
9-MRV-74 

MONITR.  SVS  22  5-MRV-74 

<  UNUSED  >  2 

F'R  .  SVS  2  5-MRV-74 

PP  . SVS  2  9-MRV-74 

<  UNU5ED  >  526 

2  FILES,  26  BLOCKS 
528  FREE  BLOCKS 


If  the  command: 

*DT1 : PP. SVS=PP. SVS/V/X 

had  been  entered,  the  new  directory  would  appear: 


4-12 


Peripheral  Interchange  Program 
9-MRY-74 


MONITR. SYS 

22 

5-MfiV-74 

PP 

.  s VS 

2 

9-MAV-74 

PR 

.  svs 

2 

5-MfiV-74 

<  UNUSED  > 

528 

3  FILES.  36  BLOCKS 
528  FREE  BLOCKS 

4.2.4  The  Extend  and  Delete  Operations 

The  /T  switch  is  used  to  increase  the  number  of  blocks  allocated  for 
the  specified  file.  The  file  associated  with  the  /T  switch  must  be 
followed  by  a  numeric  argument  of  the  form  [n]  where  n  is  a  decimal 
number  indicating  the  number  of  blocks  to  be  allocated  to  the  file  at 
the  completion  of  the  extend  operation. 

The  format  of  the  /T  switch  is: 

devsfilnam.ext [n]=/T 

A  file  can  be  extended  in  this  manner  only  if  it  is  followed  by  an 
unused  area  of  sufficient  size  (on  whichever  device  it  is  located)  to 
accommodate  the  additional  length  of  the  extended  file.  It  may  be 
necessary  to  create  this  space  by  moving  other  files  on  the  device 
using  the  /X  switch. 

Specifying  the  /T  switch  in  conjunction  with  a  file  that  does  not 
currently  exist  creates  a  file  of  the  designated  length. 

Error  messages  are  printed  if  the  /T  command  makes  the  specified  file 
smaller  (?EXT  NEG?)  or  if  there  is  insufficient  space  following  the 
file  (7R00M?) . 

Examples : 

*ftBCC 260  ]=/T  Assigns  200  blocks  to  file  ABC  on  device 

DK. 

*DT1 : XYZC 100 K/T  Assigns  100  blocks  to  the  file  named  XYZ 

on  device  DTI. 

The  /D  switch  is  used  to  delete  one  or  more  files  from  the  specified 
device.  The  wild  card  character  (*)  can  be  used  in  conjunction  with 
this  command. 

Only  six  files  can  be  specified  in  a  delete  operation  if  each  file  to 
be  deleted  is  individually  named  (i.e. ,  if  the  wild  card  character  is 
not  used) . 

A  cassette  or  magtape  may  be  initialized  by  indicating  the  /D  switch 
and  omitting  any  filenames.  For  example : 

*MT.VD 
*CT :/D 

Both  devices  are  zeroed.  This  is  not  the  case  with  the  other  RT-11 
devices,  where  omission  of  a  filename  causes  no  action  to  occur. 
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When  a  file  is  deleted  on  block-replaceable  devices,  the  information 
is  not  destroyed.  The  file  name  is  merely  removed  from  the  directory. 
If  a  file  has  been  deleted  but  not  overwritten,  it  can  be  recovered 
with  the  /T  switch  by  specifying  a  command  of  the  forms 

filena.ext [n]-/T 

where  filena.ext  is  the  name  desired  and  n  is  the  length  of  the 
deleted  file.  For  example: 

♦DTI :/E 
4-JUN-74 


R 

.  MRC 

18 

3-JUN-74 

B 

.  MRC 

17 

3-J UN-74 

C 

.  MRC 

19 

3-JUN-74 

£ 

UNUSED  > 

510 

3 

FILES,  54 

BLOCKS 

510  FREE  BLOCKS 

*DT1  :  B.  MRC/D 

♦DTI : /E 

4-JUN-74 

R  .  MRC 

18 

3-JUN-74 

<  UNUSED  > 

17 

C  .  MRC 

19 

3-JUN-74 

<  UNUSED  > 

510 

2  FILES,  3? 

BLOCKS 

52?  FREE  BLOCKS 

File  B.MAC  could  now  be  recovered  bys 


* D T 1 : B .  MRCC1?3*/T 


The  /T  switch  looks  for  the  first  unused  area  large  enough  to 
accommodate  the  requested  file  length.  If  the  file  to  be  recovered  is 
in  the  first  area  large  enough  to  accommodate  the  size  specified,  the 
preceding  command  is  sufficient.  If  not,  all  larger  unused  spaces 
preceding  the  desired  file  must  be  given  dummy  names  before  the 
recovery  can  be  made. 

For  instance,  assume  the  previous  example  with  the  exception  that 
A. MAC  has  a  33  block  unused  file  before  it,  so  that  the  directory 
looks  like: 


♦  DTWE 
4-JUN-74 


UNUSED  > 
.  MRC 
UNUSED  > 
.  MRC 
UNUSED  > 


33 
18 
1? 
19 
4  ?  7 


3-JUN-74 


3- JUN-74 


FILES,  37  BLOCKS 
52?  FREE  BLOCKS 


A  recovery  of  B.MAC  would  require: 

♦  DTI : D  U  M  M  V  C  33  3  =  /  T 

♦  DTI  :  B.  MfiCC  17  3  =  /T 
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If  the  33  block  unused  area  was  not  named  prior  to  B.MAC,  the  first  17 
blocks  of  the  33  block  area  would  become  B.MAC.  Note  that  magtape  and 
cassette  files  cannot  be  recovered  once  deleted. 

Examples : 


*FILE1.  SflV/D 


Deletes  FILEl.SAV  from  device  DK. 


*DT1:*.  *,'D  Deletes  all  files  from  device  DTI  except 

those  with  a  .SYS  or  .BAD  extension.  If 
there  is  a  file  with  a  .SYS  or  .BAD 
extension,  the  message  ?N0  SYS  ACTION? 
is  printed  to  remind  the  user  that  these 
files  have  not  been  deleted. 

**•  MRC.-'D  Deletes  all  files  with  a  .MAC  extension 

from  device  DK. 

*DT1 :  Bl,  DT2  :  Rl,  DT3  :  ftfVD 

Deletes  the  files  specified  from  the 
associated  devices. 


*RKi i*.*/n/Y  Deletes  all  files  from  device  RK1. 


4.2.5  The  Rename  Operation 

The  /R  switch  is  used  (in  a  manner  similar  to  the  multiple  copy 
command  described  in  Section  4.2.3)  to  rename  a  file  given  as  input 
with  the  associated  name  given  in  the  output  specification.  There 
must  be  an  equal  number  of  input  and  output  files  and  they  must  reside 
on  the  same  device,  or  an  error  message  will  be  printed.  The  /Y 
switch  must  be  used  in  conjunction  with  /R  if  .SYS  files  are  to  be 
renamed. 

The  Rename  command  is  particularly  useful  when  a  file  on  disk  or 
DECtape  contains  bad  blocks.  By  renaming  the  file  with  a  .BAD 
extension,  the  file  permanently  resides  in  that  area  of  the  device  so 
that  no  other  attempts  to  use  the  bad  area  will  occur.  Once  a  file  is 
given  a  .BAD  extension  it  cannot  be  moved  during  a  compress  operation. 
.BAD  files  are  not  renamed  in  wild  card  operations  unless  /Y  is  used. 

Examples  t 


*DT1 : Fl< X1CDT1.F0, X0/R 

♦  FILE1.  *<FILE2.  */R 

4.2.6  Directory  List  Operations 


Renames  FO  to  FI  and  XO  to  XI  on 
device  DTI. 

Renames  all  files  on  device  DK  with 
the  name  FILE2  (except  files  with 
.SYS  or  .BAD  extension)  to  FILEl, 
retaining  the  original  extensions. 


The  /L  switch  lists  the  directory  of  the  specified  device.  The 
listing  contains  the  current  date,  all  files  with  their  associated 
creation  dates,  total  free  blocks  on  the  device  if  disk  or  DECtape, 
the  number  of  files  listed,  and  number  of  blocks  used  by  the  files 
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(sequence  number  for  cassette)*  File  lengths ,  number  of  blocks  and 
number  of  files  are  indicated  as  decimal  values.  If  no  output  device 
is  specified,  the  directory  is  output  to  the  terminal  (TTs) • 


Examples : 

♦  DT1.VL 


1-RUG 

-74 

MON  I TR 

.  SVS 

32 

5-MRV-74 

PP 

.  SVS 

2 

9-MRV-74 

PR 

.  SVS 

2 

5-MRV-74 

F2 

.  REL 

15 

MERGE 

2 

COMB 

2 

6  FILES,  55 

BLOCKS 

509  FREE  BLOCKS 


*DIRECT=0T3:/L 


**.  MfiC/L 
l-RUG-74 

VTMRC  .  MRC  ?  22-JUL-74 

FILE2  .  MRC  1 

2  FILES/  B  BLOCKS 
3728  FREE  .BLOCKS 


*CT 1 : /L 
10-SEP-74 
PflTl  . FOR 

0 

10-SEP-74 

PftT2 

.  FOR 

0 

10- SEP- 74 

IMUL 

.  OBJ 

0 

10-SEP-74 

SQRT 

.  FTN 

0 

10-SEP-74 

4  FILES,  0 

BLOCKS 

Outputs  complete  directory  of 
device  DTI  to  the  terminal. 


Outputs  complete  directory  of 
device  DT3  to  a  file,  DIRECT, 
on  the  device  DK. 

Lists  on  the  terminal  a 
directory  of  files  on  device 
DK  with  the  extension  .MAC. 


Lists  a  directory  of  all 
files  on  cassette  drive  1. 


The  /E  switch  lists  the  entire  directory  including  the  unused  areas 
and  their  sizes  in  blocks  (decimal) ;  an  empty  space  appears  in 
cassette  and  magtape  directories  to  designate  a  deleted  file. 


Examples : 


*/E 

9  ““SEP-74 


BATCH  ♦ HLP 

2 

23-AUG-74 

CHESS  *SAO 

20 

23- AUG- 74 

PAT1  ♦ FOR 

10 

23- AUG- 74 

IRAD50 ♦ MAC 

S 

23- AUG- 7 4 

Outputs  to  the  terminal  a 
complete  directory  of  the 
device  DK  including  the  size 
of  unused  areas. 
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<  UNUSED  > 

2 

TRIG  . OBJ 

2 

6-SEP— 74 

STP  .OBJ 

2 

6— SEP— 74 

BAG  .OBJ 

n 

6-SEP- 7 4 

<  UNUSED  > 

20 

♦ 

LIBR1  ♦ OBJ 

137 

6-SEP-74 

DIRECT 

1 

9-SEP-74 

<  UNUSED  > 

230 

254  FILES » 

4280 

BLOCKS 

498  FREE  BLOCKS 

*LP . =CT1 : /E 

H-SEP-74 

A  .MAC 

0 

lt-SEP-74 

A  .MAC 

0 

U-SEp.74 

B  .MAC 

0 

U,8EP^7« 

3  FILES,  0  BLOCKS 

The  /F  switch  lists  only  filenames, 
associated  dates. 

Examples : 

*DT0 . 7F 
TRACE  .  MAC 
CARGO  .  REL 
BMAP  . OBJ 
AAA 


Outputs  to  the  line  printer 
a  complete  directory  of 
cassette  drive  1.  0's 
represent  segment  numbers. 


omitting  the  file  lengths  and 


Outputs  a  filename  directory 
of  the  device  DTO  to  the 
terminal. 


*LP : =CT1 : /F  Outputs  a  filename  directory 

of  the  device  CT1  to  the  line 
printer. 

A  .MAC 
A  .MAC 
B  .MAC 

The  /L,  /E  and  /F  commands  have  no  effect  on  the  files  of  the 
specified  device.  If  the  /W  switch  is  used  in  conjunction  with  the 
/F,  /L,  or  /E  switches,  the  absolute  starting  block  of  the  file  and 
extra  words  (in  octal)  will  be  included  in  the  listing  (for  all  but 
cassette  and  magtape) .  For  example: 


*RK1  J/L/W 


1 0- SEP- 7 4 
DSQRT  ♦ OBJ 

1 

1 0- SEP -74 

16 

MAIN  ♦ OBJ 

1 

10-SEP-74 

17 

BAS ICR ♦ OBJ 

1 1 

10-SEP-74 

20 

0TSV2  ♦ OBJ 

3 

10 -SEP -7 4 

33 

0 

0 

0 

0 


The  first  three  columns  indicate  the  filename  and  extension,  block 
length,  and  date.  The  fourth  column  shows  the  absolute  starting  block 
(in  octal) ,  and  the  fifth  column  shows  the  contents  of  each  extra  word 
per  directory  entry  (in  octal).  (This  is  allocated  using  the  /Z:n 
switch;  see  Section  4.2.7.) 
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Using  the  /L,  /E,  or  /F  switch  in  conjunction  with  a  device  and 
filename  causes  the  filename ,  and  optionally  the  date  and  file  length, 
to  be  output  rather  than  a  directory  of  the  entire  device.  For 
example : 

*F1.  SRV7L 


causes : 


4- JUN-74 

FI  .  SAY  16  4-JUN-74 

2710  FREE  BLOCKS 
* 

to  be  output,  providing  the  file  exists  on  device  DK. 

Directories  are  made  up  of  segments  which  are  two  blocks  long.  Full 
directory  listings  with  multiple  segments  contain  blank  lines  as 
segment  boundaries. 


4.2.7  The  Directory  Initialization  Operation 

The  /Z  switch  clears  and  initializes  the  directory  on  the  specified 
device  (writes  a  logical  end— of— tap©  tile  to  cassette  and  magtape) •  /Z 
must  always  be  used  to  create  an  empty  file  directory  before  using  a 
volume  for  the  first  time. 

The  form  of  the  switch  is: 

/Z:n 

where  n  is  an  octal  number  specifying  the  number  of  extra  words  per 
directory  entry.  If  n  is  not  used,  no  extra  words  are  allocated  and 
70  entries  can  be  made  in  a  directory  block.  When  extra  words  are 
allocated,  the  formula  for  determining  the  number  of  entries  per 
directory  block  is: 

507/(  (#  of  extra  words)+7) 

For  example,  if  the  switch  /Z:l  is  used,  63  entries  can  be  made  per 
block. 

When  /Z  is  used,  PIP  responds  as  follows: 

device/Z  ARE  YOU  SURE  ? 

For  example: 

*DT1 : 72 

DTI: 72  ARE  YOU  SURE  ? 

Answer  Y  and  a  carriage  return  to  perform  the  initialization.  An 
answer  beginning  with  a  character  other  than  Y  is  considered  to  be  no. 

Example : 

*DT1 :72 

D T i : 7 2  ARE  YOU  SURE  ?Y<CR> 

*  Zeroes  the  directory  on  device  DTI  and 

allocates  no  extra  words  for  the 
directory. 
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The  /N  switch  is  used  with  /Z  to  specify  the  number  of  directory 
segments  for  entries  in  the  directory.  The  form  of  the  switch  is: 

/N:n 

where  n  is  an  octal  number.  If  n  is  not  specified,  four  segments  are 
allocated.  The  maximum  number  of  segments  which  can  be  allocated  is 
37(8) . 

Example : 

*RK1 5 /Z  *  2/N  *  6  Zeroes  the  directory  on  device  RK1, 

allocates  two  extra  words  per  directory 
entry  and  allocates  six  directory 
segments  for  entries. 


4.2.8  The  Compress  Operation 

The  /S  switch  is  used  to  compress  the  directory  and  files  on  the 
specified  device,  condensing  all  the  free  (unused)  blocks  into  one 
area. 

Input  errors  are  reported  on  the  console  terminal  unless  the  /G  switch 
is  used;  output  errors  are  always  reported.  In  either  case,  the 
compress  continues.  /S  can  also  be  used  to  copy  DECtapes  and  disks 
(/S  will  not  copy  the  bootstrap  file  in  absolute  blocks  0  and  2) .  It 
is  important  to  note  that  the  /S  switch  destroys  any  previous 
directory  on  the  output  device.  The  new  directory  on  the  output 
device  will  have  the  same  number  of  segments  as  the  directory  on  the 
input  device. 

To  increase  the  number  of  directory  blocks  in  a  two-volume  compress 
(that  is,  from  one  volume  to  another  rather  than  from  one  volume  to 
itself),  use  the  /N:n  switch  in  conjunction  with  the  /S  switch  (any 
attempts  to  decrease  the  directory  size  are  ignored) . 

/S  does  not  move  files  with  the  .BAD  extension.  This  feature  provides 
protection  against  reusing  bad  blocks  which  may  occur  on  a  disk. 
Files  containing  bad  blocks  can  be  renamed  with  the  .BAD  extension  and 
are  then  left  in  place  when  a  /S  is  executed. 

If  a  compress  operation  is  performed  on  the  system  device,  the 
message : 

7REB00T? 

is  printed  to  indicate  that  it  may  be  necessary  to  reboot  the  system. 
If  .SYS  files  were  not  moved  during  the  compress  operation,  it  is  not 
necessary  to  reboot  the  system. 


NOTE 

Rebooting  the  system  in  response  to  the 
PREBOOT?  warning  message  should  ONLY  be 
done  AFTER  the  operation  which  generated 
the  message  is  complete.  PREBOOT?  does 
not  signify  that  the  system  should  be 
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rebooted  immediately;  the  user  should 
wait  for  the  signifying  that  PIP  is 
ready  for  another  command  before 
rebooting. 


If  the  command  attempts  to  compress  a  large  device  to  a  smaller  one, 
an  error  results  and  the  directory  of  the  smaller  device  is  zeroed. 
If  a  device  is  being  compressed  in  place,  input  and  output  errors  are 
reported  on  the  terminal  and  the  operation  continues  to  completion. 

Examples: 


*  S  V  :  /  5 
7REB00T? 


Compresses  the  files  on  the  system 
device  SY: 


*  D  T 1 :  ft  <  D  T  2  :  /  5  Transfers  and  compresses  the  files  from 

device  DT2  to  device  DTI,  Device  DT2  is 
not  changed.  The  filename  A  is  a  dummy 
specification  required  by  the  Command 
String  Interpreter, 

/S  cannot  be  used  when  a  foreground  job  is  present;  a  ?FG  PRESENT? 
error  message  results  if  this  is  attempted. 


4.2.9  The  Bootstrap  Copy  Operation 

The  bootstrap  copy  switch  (/U)  copies  the  bootstrap  portion  of  the 
specified  file  into  absolute  blocks  0  and  2  of  the  specified  device. 

Examples : 

*DK : ft  <  D  K : MONI TR.  SVS/U 

Writes  the  bootstrap  file  MONITR,SYS  in 
blocks  0  and  2  of  the  device  DK.  A  is  a 
dummy  filename. 

*DT0 : F2  =  DK : MGNITR.  SVS/U 

Writes  the  bootstrap  file  MONITR.SYS 
into  blocks  0  and  2  of  the  device  DTO • 
The  filename  F2  is  a  dummy  specification 
required  by  the  Command  String 
Interpreter. 


4.2.10  The  Boot  Operation 

The  boot  switch  reboots  the  system,  reinitializing  monitor  tables  and 
returning  the  system  to  the  monitor  level.  The  boot  switch  performs 
the  same  operation  as  a  hardware  bootstrap. 

Example: 


*DK:/0  Reboots  the  device  DK. 
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If  a  boot  switch  is  specified  on  a  non-file  structured  device,  the 
message: 

?BAD  BOOT? 

is  printed.  Legal  system  devices  are  DTO ,  RK0-RK7,  RF,  SY,  and  DK. 
Note  that  /0  is  legal  if  a  foreground  job  is  present;  the  ?FG 
PRESENT?  error  message  results. 


4.2.11  The  Version  Switch 

The  Version  switch  (/V)  outputs  a  version  number  message  (representing 
the  version  of  PIP  in  use)  to  the  terminal  using  the  form: 

PIP  V02-XX 

The  rest  of  the  command  line,  if  any,  is  ignored. 


4.2.12  Bad  Block  Scan  (/K) 

The  bad  block  switch  (/K)  scans  the  specified  device  and  types  the 
absolute  block  numbers  of  those  blocks  on  the  device  which  return 
hardware  errors.  The  block  numbers  typed  are  octal;  the  first  block 
on  a  device  is  0(8).  Note  that  if  no  errors  occur,  nothing  will  be 
output.  A  complete  scan  of  a  disk  pack  takes  several  minutes. 

Example : 

KRK2J/K  Scan  disk  drive  2  for  bad  blocks. 

BLOCK  140  IS  BAD 

*RK : /K  Scan  drive  1.  No  blocks  are  bad. 

* 


4.2.12.1  Recovery  from  Bad  Blocks 

As  a  disk  ages,  the  recording  surface  wears.  Eventually  unrecoverable 
I/O  errors  occur  during  attempts  to  read  or  write  a  bad  disk  block. 
PIP  protects  against  usage  of  bad  disk  areas  by  ignoring  files  with  a 
.BAD  extension  (unless  the  /Y  switch  is  used) .  Once  a  bad  block  is 
uncovered  in  an  I/O  operation,  it  can  be  located  using  the  /K  switch 
and  a  .BAD  file  can  be  created  which  encompasses  the  bad  block. 

When  a  hardware  I/O  error  is  detected,  the  recovery  procedure  is  as 
follows : 

1.  Use  the  PIP  /K  switch  to  seem  the  device  and  print  on  the 
terminal  the  absolute  block  numbers  (in  octal)  of  the  bad 
blocks.  For  example: 

.  R  PIP 
*RK1 : /K 

BLOCK  7722  IS  BAD 
* 
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2.  Obtain  an  extended  directory  with  the  /W  switch ,  showing  the 
starting  block  numbers  of  all  the  files  on  the  disk. 

3.  If  a  bad  block  occurs  in  a  file  with  valuable  information, 
copy  the  file  to  another  file  using  the  /G  switch.  In  most 
cases,  only  1  bit  (character)  of  the  file  is  affected. 

4.  If  the  file  is  small,  it  can  then  be  renamed  with  a  .BAD 
extension  to  prevent  further  use  of  that  disk  area. 


5.  If  the  file  is  large  or  the  bad  block  occurs  in  an  empty 
area,  a  1-block  .BAD  file  can  be  created  using  the  /T  switch 
as  follows: 


a.  Delete  the  bad  file  (if  any) . 


b.  If  the  bad  block  is  at  block  n  of  the  free  area,  create  a 
file  of  length  n-1  with  the  /T  switch.  Remember  that 
there  must  be  no  spaces  larger  than  n-1  blocks  before  the 
desired  one  (refer  to  Section  4.2.4).  Also  note  that  the 
block  numbers  printed  in  the  /K  and  /W  operations  are 
octal,  while  the  argument  to  the  /T  operation  is  decimal. 

c.  Create  a  1-block  .BAD  file  with  the  /T  switch  to  cover 
the  bad  block. 

d.  Delete  any  temporary  files  created  during  the  operation. 


For  example,  assume  the  extended  directory  is: 


NEMSHC.8AT 

8 

ll-SEP-74 

RTTEMP.BAT 

27 

ll-SEP-74 

PIP  .MAC 

150 

12-SEP-74 

4  UNUSED  > 

154 

VERIFY. 8AV 

3 

<  UNUSED  » 

300 

PIP  .OBJ 

15 

12-SEP-74 

MKPIP  ,CT|. 

1 

12-SEP-74 

MKV2RK.CTL 

4 

12-SEP-74 

VTLIB  .OBJ 

10 

12-SEP-74 

«  UNUSED  * 

150 

A 

4 

12-SEP-74 

PIP  .LST 

300 

3-SEP-74 

6203 

6213 

6246 

6726 

740b 

7424 

7425 
7431 

7671 

7675  Block  7723  (octal)  of 
PIP.LST  is  bad. 


and  a  bad  block  is  detected  at  block  7723  (octal)  of  the  file  PIP.LST. 
To  recover,  make  a  copy,  ignoring  the  error,  and  delete  the  bad  file: 


*RKl:PIPfl.  LST  =  RK1 : PIP.  LST/G 
*RK1 : PIP.  LST /D 


The  directory  now  reads: 


NEWSRC.BAT  8 
RTTEMP.BAT  27 
PIP  .MAC  150 


ll-SEP-74  6203 

11- SEP-74  6213 

12- SEP-74  6246 
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<  UNUSED  > 

154 

VERIFY. SAV 

3 

PIPA  ,LST 

300 

PIP  .OBJ 

15 

MKPIP  ,CTL 

1 

MKV2RK.CTL 

4 

VTLIB  .OBJ 

10 

«  UNUSED  > 

150 

A 

4 

1S-SEP-74 

6726 

6731 

12-SEP-74 

7405 

12-SEP-74 

7424 

12-SEP-74 

7425 

12-SEP-74 

7431 

12-SEP-74 

7671 

An  unused  area  following  A  contains  block  7723  (octal) ,  which 
is  bad.  Continuing  in  PIPs 

*RK1 :  TEMP.  002C154  3=/T 
*RK1 : TEMP.  003[ 150 1=/T 
*RK1 :  TEMP.  004[22]=/T 

This  fills  the  unused  areas  with  temporary  files.  Specifying 
TEMP. 004  with  a  length  of  22  blocks  makes  the  file  just  long 
enough  to  precede  the  bad  block  (i.e.,  7675  (octal)  and  20 
(decimal)  equal  7723,  which  would  be  the  starting  block 
number  of  the  next  file  created) .  The  directory  now  contains  s 


NEWSRC.BAT 

8 

ll-SEP-74 

RTTEMP.BAT 

27 

ll-SEP-74 

PIP  .MAC 

150 

12-SEP-74 

TEMP  ,002 

154 

18-SEP-74 

VERIFY. SAV 

3 

PIPA  , LST 

300 

18-SEP-74 

PIP  .OBJ 

15 

12-SEP-74 

MKPIP  .CTL 

1 

12-SEP-74 

MKV2RK.CTL. 

4 

12-SEP-74 

VTLIB  .OBJ 

10 

12-SEP-74 

TEMP  .003 

150 

18-SEP-74 

A 

4 

12-SEP-74 

TEMP  .004 

• 

22 

18-SEP-74 

• 

Continuing  with 

PIP: 

*RK1 : F I LE. 

BflDC i 3=/V/T 

The  directory  now  contains: 

• 

• 

NEWSRC.BAT 

8 

ll-SEP-74 

RTTEMP.BAT 

27 

1 l-SEP-74 

PIP  .MAC 

150 

1 2-SEP-74 

TEMP  ,002 

154 

18-SEP-74 

VERIFY, SAV 

3 

PIPA  .LST 

300 

18-SEP-74 

PIP  .OBJ 

15 

12-SEP-74 

MKPIP  .CTL 

1 

12-SEP-74 

MKV2RK.CTL 

4 

1 2-SEP-74 

VTLIB  .OBJ 

10 

12-SEP-74 

TEMP  .003 

150 

18-SEP-74 

A 

4 

12-SEP-74 

6203 

6213 

6246 

6474 

6726 

6731 

7405 

7424 

7425 
7431 
7443 
7671 
7675 


Create  a  bad  file. 


6203 

6213 

6246 

6474 

6726 

6731 

7405 

7424 

7425 
7431 
7443 
7671 
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TEMP  ,004  22  18-SEP-74  7675 
FILE  .BAD  1  18-SEP-74  7723 


Next  delete  all  temporary  files  and  rename  PIPA.LST  to 
PIP.LST.  The  final  directory  now  contains: 


NEWSRC.BAT 

8 

ll-SEP-74 

6203 

RTTEMP.BAT 

27 

ll-SEP-74 

6213 

PIP  .MAC 

150 

12-SEP-74 

6246 

<  UNUSED  > 

1 54 

VERIFY. SAV 

3 

6726 

PIP  ,LST 

300 

18-SEP-74 

6731 

PIP  .OBJ 

15 

12-SEP-74 

7405 

MKPIP  . CTL 

1 

12-SEP-74 

7424 

MKV2RK.CTL 

4 

12-SEP-74 

7425 

VTLIB  .OBJ 

10 

12-SEP-74 

7431 

<  UNUSED  > 

150 

A 

4 

12-SEP-74 

7671 

<  UNUSED  > 

22 

FILE  .BAD 

1 

18-SEP-74 

7723 

Disks  with  many  bad  blocks  can  often  be  reused  by 
reformatting  them.  First  copy  all  desired  files,  since 
reformatting  destroys  all  information  contained  on  a  volume. 


4.3  PIP  ERROR  MESSAGES 


The  following  error  messages  are  output  on  the  terminal  when  PIP  is 
used  incorrectly: 

Errors  Meaning 


7B00T  COPY? 

?CHK  SUM? 

?COR  OVR? 


An  error  occurred  during  an  attempt  to  write 
bootstrap  with  /U  switch. 

A  checksum  error  occurred  in  a  formatted 
binary  transfer. 

Memory  overflow — too  many  devices  and/or  file 
specifications  (usually  *.*  operations)  and 
no  room  for  buffers. 


?DEV  FUL? 
?ER  RD  DIR? 


?ER  WR  DIR? 


No  room  on  device  for  file. 

Unrecoverable  error  reading  directory.  Check 
volume  for  off-line  or  write-locked  condition 
and  try  the  operation  again. 

Unrecoverable  error  writing  directory.  Try 
again. 


?EXT  NEG? 


A  /T  command  attempted  to  make  file  smaller. 


?FG  PRESENT?  An  attempt  was  made  to  use  /0  or  /S  while  a 

foreground  job  was  still  in  memory.  Unload 
it  if  it  is  no  longer  desired. 


?FIL  NOT  FND?  File  not  found  during  a  delete,  copy,  or 

rename  operation. 
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?ILL  CMD? 

The  command  specified  was  not  syntactically 
correct;  a  device  name  is  missing  which 
should  be  specified,  a  switch  argument  is  too 
large,  a  filename  is  specified  where  one  is 
inappropriate,  or  a  non— file  structured 
device  is  specified  for  a  file-structured 
operation. 

PILL  DEV? 

Illegal  or  nonexistent  device. 

PILL  SWT? 

Illegal  switch  or  switch  combination. 

PILL  REN? 

Illegal  rename  operation.  Usually  caused  by 
different  device  names  on  the  input  and 
output  sides  of  the  command  string. 

PIN  ER? 

Unrecoverable  error  reading  file.  Try  again 
(this  error  is  ignored  during  /G  operation) . 

POUT  ER? 

Unrecoverable  error  writing  file.  Perhaps  a 
hardware  or  checksum  error;  try  recopying 
file.  Also  may  be  caused  by  an  attempt  to 
compress  a  larger  device  to  a  smaller  one  or 
by  not  enough  room  when  creating  a  file.  The 
system  takes  the  largest  space  available  and 
divides  it  in  half  before  attempting  to 
insert  the  file.  Try  the  (]  construction  or 
/X  switch. 

POUT  PIL? 

Illegal  output  file  specification  or  missing 
output  file. 

PROOM? 

Insufficient  space  following  file  specified 
with  a  /T  switch. 

The  following  warning  messages  are  output  by  PIP: 
CTn:  PUSH  REWIND  OR  MOUNT  NEW  VOLUME 


?N0  SYS  ACTION? 

A  new  cassette  must  be  mounted  on  drive  n  to 
allow  continuation  of  an  I/O  operation.  The 
operation  is  continued  automatically  as  soon 
as  the  new  cassette  is  mounted. 

The  /Y  switch  was  not  included  with  a  command 
specified  on  a  .SYS  file.  The  command  is 
executed  for  all  but  the  .SYS  files.  A  *.* 

transfer  is  most  likely  to  cause  this 
message. 


? REBOOT? 

.SYS  files  have  been  brans f erred ,  renamed , 
compressed  or  deleted  from  the  system  device. 
It  may  be  necessary  to  reboot  the  system. 

NOTE 

The  message  is  typed  immediately 
after  execution  of  the  relevant 
command  has  begun ,  but  the 
actual  reboot  operation  must  not 
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be  performed  until  PIP  returns 
with  the  prompting  asterisk  for 
the  next  command.  If  the  system 
is  halted  and  rebooted  before 
the  prompting  asterisk  returns, 
disk  information  may  be  lost. 

If  any  of  the  .SYS  files  in  use  by  the 
current  system  (MONITR.SYS  and  handler  files) 
have  been  physically  moved  on  the  system 
device,  it  is  necessary  to  reboot  the  system 
immediately.  If  not,  this  message  can  be 
ignored.  If  the  cause  of  the  message  was  a 
/S  operation,  the  system  need  be  rebooted 
only  if  there  was  an  empty  space  before  any 
of  the  .SYS  files  or  if  the  /N:n  switch  was 
used  to  increase  the  number  of  directory 
segments.  The  need  to  reboot  can  be 
permanently  avoided  by  placing  all  .SYS  files 
at  the  beginning  of  the  system  device,  then 
avoiding  their  involvements  in  PIP  operations 
by  not  using  the  /Y  switch. 
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MACRO  is  a  2-pass  macro  assembler  requiring  an  RT-11  system 
configuration  (or  background  partition)  of  12K  or  more.  Macros  are 
instructions  in  a  source  or  command  language  which  are  equivalent  to  a 
specified  sequence  of  machine  instructions  or  commands.  Users  with 
minimum  memory  configurations  must  use  ASEMBL  and  EXPAND  and  should 
read  this  chapter  and  Chapters  10  and  11  before  assembling  any 
programs.  (The  macro  features  not  supported  by  ASEMBL  are  indicated 
in  this  chapter;  many  of  the  features  not  available  in  ASEMBL  are 
supported  by  EXPAND.) 

Some  notable  features  of  MACRO  ares 

1.  Program  control  of  assembly  functions 

2.  Device  and  file  name  specifications  for  input  and  output 

files  c 

3.  Error  listing  on  command  output  device 

4.  Alphabetized,  formatted  symbol  table  listing 

5.  Relocatable  object  modules 

6.  Global  symbols  declaration  for  linking  among  object  modules 

7.  Conditional  assembly  directives 

8.  Program  sectioning  directives 

9.  User  defined  macros 

10.  Comprehensive  set  of  system  macros 

11.  Extensive  listing  control,  including  cross  reference  listing 
Operating  instructions  for  the  MACRO  assembler  appear  in  Section  5.7. 
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5.1  SOURCE  PROGRAM  FORMAT 

A  source  program  is  composed  of  a  sequence  of  source  lines; 
source  line  contains  a  single  assembly  language  statement  followed  by 
a  statement  terminator.  A  terminator  may  be  either  a  line  feed 
character  (which  increments  the  line  count  by  1)  or  a  form  feed 
character  (which  increments  both  the  line  count  and  page  count  by  1) • 


NOTE 

EDIT  automatically  appends  a  line  feed 
to  every  carriage  return  encountered  in 
a  source  program.  For  listing  format, 

MACRO  automatically  inserts  a  carriage 
return  before  any  line  feed  or  form  feed 
not  already  preceded  by  one. 

An  assembly  language  line  can  contain  up  to  132 (decimal)  characters 
(exclusive  of  the  statement  terminator) .  Beyond  this  limit,  excess 
characters  are  ignored  and  generate  an  error  flag. 


5.1.1  Statement  Format 

A  statement  can  contain  up  to  four  fields  which  are  identified  by 
order  of  appearance  and  by  specified  terminating  characters.  The 
general  format  of  a  MACRO  assembly  language  statement  is: 

label:  operator  operand (s)  ; comments 

The  label  and  comment  fields  are  optional.  The  operator  and  operand 
fields  are  interdependent?  either  may  be  omitted  depending  upon  the 
contents  of  the  other. 

The  assembler  interprets  and  processes  these  statements  one  by  one, 
generating  one  or  more  binary  instructions  or  data  words  or  performing 
an  assembly  process.  A  statement  contains  one  of  these  fields  and  may 
contain  all  four  types.  Blank  lines  are  legal. 

Some  statements  have  one  operand,  for  example: 

CL*  R0 

while  others  have  two: 

MOV  #344,R2 

An  assembly  language  statement  must  be  complete  on  one  source  line. 
No  continuation  lines  are  allowed.  (If  a  continuation  is  attempted 
with  a  line  feed,  the  assembler  interprets  this  as  the  statement 
terminator. ) 

MACRO  source  statements  may  be  formatted  with  EDIT  so  that  use  of  the 
TAB  character  causes  the  statement  fields  to  be  aligned.  For  example: 
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Label 

Operator 

Operand 

Comment 

Field 

Field 

Field 

Field 

CHECK: 

BIT 

#1,R0 

; IS  NUMBER  ODD? 

BEQ 

EVEN 

;NO,  IT 1 S  EVEN 

MOV 

#-l /ODDFLG 

yELSE  SET  FLAG 

EVEN: 

RTS 

PC 

; RETURN 

5. 1.1.1 

Label  Field 

-  A  label  is  a  user-defined  symbol  that  is 

unique 

within  the 

first  six  characters 

and  is  assigned  the  value  of 

the  current  location  counter  and  entered  into  the  user-defined  symbol 
table.  The  value  of  the  label  may  be  either  absolute  (fixed  in  memory 
independently  of  the  position  of  the  program)  or  relocatable  (not 
fixed  in  memory) ,  depending  on  whether  the  location  counter  value  (see 
Section  5,2,6)  is  currently  absolute  or  relocatable. 

A  label  is  a  symbolic  means  of  referring  to  a  specific  location  within 
a  program.  If  present,  a  label  always  occurs  first  in  a  statement  and 
must  be  terminated  by  a  colon.  For  example,  if  the  current  location 
is  absolute  100 (octal),  the  statement: 

ABCDl  MOV  A  9 B 

assigns  the  value  100 (octal)  to  the  label  ABCD.  Subsequent  reference 
to  ABCD  references  location  100 (octal).  In  this  example  if  the 
location  counter  was  declared  relocatable  within  the  section,  the 
final  value  of  ABCD  would  be  100 (octal)  plus  a  value  assigned  by  LINK 
when  it  relocates  the  code,  called  the  relocation  constant.  (The 
final  value  of  ABCD  would  therefore  not  be  known  until  link-time. 
This  is  discussed  later  in  this  chapter  and  in  Chapter  6.) 

More  than  one  label  may  appear  within  a  single  label  field,  in  which 
case  each  label  within  the  field  is  assigned  the  same  value.  For 
example,  if  the  current  location  counter  is  100 (octal),  the  multiple 
labels  in  the  statement: 

ABC  f  ER*EX|  MASKI  MOV  A#  B 

cause  each  of  the  three  labels— ABC,  ERREX,  and  MASK— to  be  equated  to 
the  value  100 (octal). 

A  symbol  used  as  a  label  may  not  be  redefined  within  the  user  program. 
An  attempt  to  redefine  a  label  results  in  an  error  flag  in  the 
assembly  listing. 


5. 1.1.2  Operator  Field  -  An  operator  field  follows  the  label  field 
in  a  statement  and  may  contain  a  macro  call,  an  instruction  mnemonic, 
or  an  assembler  directive.  The  operator  may  be  preceded  by  zero,  one 
or  more  labels  and  may  be  followed  by  one  or  more  operands  and/or  a 
comment.  Leading  and  trailing  spaces  and  tabs  are  ignored. 

When  the  operator  is  a  macro  call,  the  assembler  inserts  the 
appropriate  code  to  expand  the  macro.  When  the  operator  is  an 
instruction  mnemonic,  it  specifies  the  instruction  to  be  generated  and 
the  action  to  be  performed  on  any  operand (s)  which  follow.  When  the 
operator  is  an  assembler  directive,  it  specifies  a  certain  function  or 
action  to  be  performed  during  assembly. 
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An  operator  is  legally  terminated  by  a  space ,  tab,  or  any 
non-alphanumeric  character  (symbol  component) . 

Consider  the  following  examples: 

MOV  A  f  B  (space  terminates  the  operator  MOV) 

MOV# A f  0  (@  terminates  the  operator  MOV) 

When  the  statement  line  does  not  contain  an  operand  or  comment,  the 
operator  is  terminated  by  a  carriage  return  followed  by  a  line  feed  or 
form  feed  character. 

A  blank  operator  field  is  interpreted  as  a  .WORD  assembler  directive 
(See  Section  5. 5. 3. 2). 


5. 1.1. 3  Operand  Field  -  An  operand  is  that  part  of  a  statement  which 
is  manipulated  by  the  operator.  Operands  may  be  expressions,  numbers, 
or  symbolic  or  macro  arguments  (within  the  context  of  the  operation) . 
When  multiple  operands  appear  within  a  statement,  each  is  separated 
from  the  next  by  one  of  the  following  characters:  comma,  tab,  space, 
or  paired  angle  brackets  around  one  or  more  operands  (see  Section 
5. 2. 1.1).  Multiple  delimiters  separating  operands  are  not  legal  (with 
the  exception  of  spaces  and  tabs--any  combination  of  spaces  and/or 
tabs  represents  a  single  delimiter) •  An  operand  may  be  preceded  by  an 
operator,  a  label  or  another  operand  and  followed  by  a  comment. 

The  operand  field  is  terminated  by  a  semicolon  when  followed  by  a 
comment,  or  by  a  statement  terminator  when  the  operand  completes  the 
statement.  For  example: 

tABEll  MOV  A# B  | CQMMf NT 

The  space  between  MOV  and  A  terminates  the  operator  field  and  begins 
the  operand  field;  a  comma  separates  the  operands  A  and  B;  a 
semicolon  terminates  the  operand  field  and  begins  the  comment  field. 


5. 1.1. 4  Comment  Field  -  The  comment  field  is  optional  and  may 
contain  any  ASCII  characters  except  null,  rubout,  carriage  return, 
line  feed,  vertical  tab  or  form  feed.  All  other  characters,  even 
special  characters  with  defined  usage,  are  ignored  by  the  assembler 
when  appearing  in  the  comment  field. 

The  comment  field  may  be  preceded  by  one,  any,  none  or  all  of  the 
other  three  field  types.  Comments  must  begin  with  the  semicolon 
character  and  end  with  a  statement  terminator. 
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Comments  do  not  affect  assembly  processing  or  program  execution,  but 
are  useful  in  source  listings  for  later  analysis,  debugging,  or 
documentation  purposes,  y' 


5.1.2  Format  Control 

Horizontal  or  line  formatting  of  the  source  program  is  controlled  by 
the  space  and  tab  characters.  These  characters  have  no  effect  on  the 
assembly  process  unless  they  are  embedded  within  a  symbol,  number,  or 
ASCII  text;  or  unless  they  are  used  as  the  operator  field  terminator. 
Thus,  these  characters  can  be  used  to  provide  an  orderly  source 
program.  A  statement  can  be  written: 

LABELlMOV(SP)+,TAG|POP  VALUE  OFF  STACK 

or,  using  formatting  characters,  it  can  be  written: 

LABfcLI  MOV  (SP] +; TAG  fPOP  VALUE  OFF  STACK 

which  is  easier  to  read  in  the  context  of  a  source  program  listing. 

Vertical  formatting,  i.e.,  page  size,  is  controlled  by  the  form  feed 
character.  A  page  of  n  lines  is  created  by  inserting  a  form  feed 
(CTRL  FORM)  after  the  nth  line.  (See  also  Section  5. 5. 1.6  for  a 
description  of  page  formatting  with  respect  to  macros  and  Section 

5. 5.1.2  for  a  description  of  assembly  listing  output.) 


5.2  SYMBOLS  AND  EXPRESSIONS 

This  section  describes  the  various  components  of  legal  MACRO 
expressions :  the  assembler  character  set,  symbol  construction, 
numbers,  operators,  terms  and  expressions. 


5.2.1  Character  Set 

The  following  characters  are  legal  in  MACRO  source  programs: 

1.  The  letters  A  through  Z.  Both  upper-  and  lower-case  letters 
are  acceptable,  although,  upon  input,  lower-case  letters  are 
converted  to  upper-case  letters.  Lower-case  letters  can  only 
be  output  by  sending  their  ASCII  values  to  the  output  device. 
This  conversion  is  not  true  for  .ASCII,  .ASCIZ,  '  (single 
quote)  or  "  (double  quote)  statements  if  . ENABL  LC  is  in 
effect. 

2.  The  digits  0  through  9. 

3.  The  characters  .  (period  or  dot)  and  $  (dollar  sign)  which 
are  reserved  for  use  in  system  program  symbols  (with  the 
exception  of  local  symbols;  see  Section  5.2.5). 

4 .  The  following  special  characters : 
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Character 


Designation 


Function 


carriage  return 
line  feed 
form  feed 
vertical  tab 


% 

tab 

space 

# 

@ 

( 


> 

+ 


/ 

& 


I 

t 

\ 


colon 

equal  sign 
percent  sign 


number  sign 
at  sign 

left  parenthesis 
right  parenthesis 
comma 
semicolon 

left  angle  bracket 

right  angle  bracket 

plus  sign 

minus  sign 

asterisk 

slash 
ampersand 
exclamation 
double  quote 
single  quote 
uparrow 

backslash 


formatting  character 
source  statement  terminators 


label  terminator 

direct  assignment  indicator 

register  term  indicator 

item  or  field  terminator 

item  or  field  terminator 

immediate  expression  indicator 

deferred  addressing  indicator 

initial  register  indicator 

terminal  register  indicator 

operand  field  separator 

comment  field  indicator 

initial  argument  or  expression 

indicator 

terminal  argument  or  expression 
indicator 

arithmetic  addition  operator  or 
auto  increment  indicator 
arithmetic  subtraction  operator 
or  auto  decrement  indicator 
arithmetic  multiplication 

operator 

arithmetic  division  operator 
logical  AND  operator 
logical  inclusive  OR  operator 
double  ASCII  character  indicator 
single  ASCII  character  indicator 
universal  unary  operator , 

argument  indicator 
macro  numeric  argument  indicator 
(not  available  in  ASEMBL) 


5.2. 1.1  Separating  and  Delimiting  Characters  -  Reference  is  made  in 
the  remainder  of  the  chapter  to  legal  separating  characters  and  macro 
argument  delimiters.  These  terms  are  defined  in  Table  5-1  and 
following. 


Table  5-1 

Legal  Separating  Characters 


Character 

Definition 

Usage 

space 

one  or  more  spaces 
and/or  tabs 

A  space  is  a  legal  separator 
only  for  argument  operands • 
Spaces  within  expressions  are 
ignored. 

9 

comma 

A  comma  is  a  legal  separator 
for  both  expressions  and 
argument  operands. 

<...> 

paired  angle  brackets 

Paired  angle  brackets  are  used 
to  enclose  an  argument , 

(Continued  on  next  page) 
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Table  5-1  (cont.) 

Legal  Separating  Characters 


Character 

Definition 

Usage 

Up  arrow  construction 
where  the  up  arrow 
character  is  followed 
by  an  argument 
bracketed  by  any  paired 
printing  characters. 

particularly  when  that 
argument  contains  separating 
characters.  Paired  angle 
brackets  may  be  used  anywhere 
in  a  program  to  enclose  an 
expression  for  treatment  as  a 
term. 

This  construction  is 
equivalent  in  function  to  the 
paired  angle  brackets  and 
is  generally  used  only  where 
the  argument  contains  angle 
brackets . 

Macro  arguments  may  appear  in  several  forms  to  allow  for  special 
cases.  The  rules  to  observe  when  separating  arguments  are: 


1.  If  an  argument  string  contains  only  non-separating  characters 
(those  not  defined  in  Table  5-1)  and  no  spaces,  then  it  may 
appear  in  the  argument  list  separated,  if  necessary,  from  the 
other  arguments  by  commas. 

2.  If  an  argument  string  contains  separating  characters  or 

spaces,  but  does  not  contain  the  characters  <  or  >  (left  or 
right  angle  brackets) ,  then  the  argument  may  appear  enclosed 
in  paired  angle  brackets  (e.g.,  <argument  string>) .  The 
paired  angle  brackets  are  removed  before  the  argument  string 
is  used.  Successive  pairs  of  angle  brackets  may  be  used  to 
enclose  an  argument;  only  the  outermost  pair  is  removed. 

3.  If  an  argument  string  contains  separating  characters  or 

spaces  (possibly  including  the  left  or  right  angle  bracket 
characters) ,  then  it  may  appear  in  the  following  form: 
t\argument  string\  where  the  backslashes  may  be  replaced  by 
any  character  not  appearing  in  the  argument  string.  The 
uparrow  and  backslashes  (or  other  character)  are  removed 
before  the  argument  string  is  substituted  into  the  text. 

Note  that  regardless  of  the  method  used  to  specify  an  argument,  it 
must  be  separated  from  any  other  arguments  by  commas. 


5. 2.1. 2  Illegal  Characters  - 
two  ways : 

A  character  can  be 

illegal  in 

one 

of 

1.  A  character  which  is 

not  recognized  as 

an  element 

of 

the 

MACRO  character  set  is  always  an  illegal  character  and  causes 
immediate  termination  of  the  current  line  at  that  point,  plus 
the  output  of  an  error  flag  in  the  assembly  listing.  For 
example : 

LABEJ>*A:  MOV  A,B 

Since  the  backarrow  is  not  a  recognized  character,  the  entire 
line  is  treated  as  a: 

.WORD  LABEL 

statement  and  is  flagged  in  the  listing. 
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2.  A  legal  MACRO  character  may  be  illegal  in  context.  Such 
character  generates  a  Q  error  on  the  assembly  listing. 


5. 2. 1.3  Operator  Characters  -  Under  MACRO ,  legal  unary 
(operators  applying  to  only  one  operand)  are  as  follows : 


operators 


Unary 


Operator 

Explanation 

+ 

plus  sign 

+A 

- 

minus  sign 

-A 

t 

uparrow,  universal 
unary  operator 
(this  usage  is 
described  in 
greater  detail 

tF3.0 

in  Sections 

5 . 5 . 4 . 2  and  5. 5. 6. 2) . 

tC24 

Example 

(positive  value 
equivalent  to  A) 

(negative ,  2*s 

value  of  A) 


of 


complement , 


tD127 


(interprets  3.0  as  a 
1-word  floating-point 
number) 


(interprets  the  one's 
complement  of  the  binary 
representation  of  24(8)) 

(interprets  127  as  a  decimal 
number) 


t034  (interprets  34  as  an  octal 

number) 


tBllOOOlll  (interprets  11000111 
binary  value) 


as  a 


The  unary  operators  described  above  can  be  used  adjacent  to  each  other 
in  a  term.  For  examples 

tCt012 

-t05 

Legal  binary  operators  under  MACRO  are  as  follows: 


Binary 

Operator 


Explanation 


Example 


+ 

addition 

A+B 

— 

subtraction 

A-B 

* 

multiplication 

A*B 

/ 

division 

A/B 

& 

logical  AND 

A&B 

l 

logical  inclusive  OR 

AIB 

All  binary  operators  have  the  same  priority.  Division  and 
multiplication  are  signed  operations.  Items  can  be  grouped  for 
evaluation  within  an  expression  by  enclosure  in  angle  brackets.  Terms 
in  angle  brackets  are  evaluated  first,  and  remaining  operations  are 
performed  left  to  right.  For  examples 

9W0R0  1+2*3  ?IS  11  OCTAL 
.WORD  U«2*3»  IIS  T  OCTAL 
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5.2.2  Symbols 

There  are  three  types  of  symbols:  permanent,  user-defined  and  macro. 
MACRO  maintains  three  types  of  symbol  tables:  the  Permanent  Symbol 
Table  (PST) ,  the  User  Symbol  Table  (UST)  and  the  Macro  Symbol  Table 
(MST) .  The  PST  contains  all  the  permanent  symbols  and  is  part  of  the 
MACRO  Assembler  load  module.  The  UST  and  MST  are  constructed  as  the 
source  program  is  assembled;  user-defined  symbols  are  added  to  the 
table  as  they  are  encountered. 


5. 2. 2.1  Permanent  Symbols  -  Permanent  symbols  consist  of  the 
instruction  mnemonics  (Appendix  C)  and  assembler  directives  and  macro 
directives  (sections  5.5  and  5.6,  Appendix  C) .  These  symbols  are  a 
permanent  part  of  the  assembler  and  need  not  be  defined  before  being 
used  in  the  source  program. 


5. 2. 2. 2  User-Defined  and  Macro  Symbols  -  User-defined  symbols  are 
those  used  as  labels  or  defined  by  direct  assignment  (Section  5.2.3). 
These  symbols  are  added  to  the  User  Symbol  Table  as  they  are 
encountered  during  the  first  pass  of  the  assembly.  Macro  symbols  are 
those  symbols  used  as  macro  names  in  the  operator  field  (Section 
5.6.1).  These  symbols  are  added  to  the  Macro  Symbol  Table  as  they  are 
encountered  during  the  assembly. 

User-defined  and  macro  symbols  can  be  composed  of  alphanumeric 
characters,  dollar  signs,  and  periods  only;  any  other  character  is 
illegal. 

The  $  and  .  characters  are  reserved  for  system  software  symbols  (for 
example,  the  system  macro  symbol  .READ);  it  is  recommended  that  $  and 
.  not  be  inserted  in  user-defined  or  macro  symbols. 

The  following  rules  apply  to  the  creation  of  user-defined  and  macro 
symbols : 

1.  The  first  character  must  not  be  a  number  (except  in  the  case 
of  local  symbols,  see  Section  5.2.5). 

2.  Each  symbol  must  be  unique  within  the  first  six  characters. 

3.  A  symbol  can  be  written  with  more  than  six  legal  characters, 
but  the  seventh  and  subsequent  characters  are  only  checked 
for  legality,  and  are  not  otherwise  recognized  by  the 
assembler. 

4.  Spaces,  tabs,  and  illegal  characters  must  not  be  embedded 
within  a  symbol. 

The  value  of  a  symbol  depends  upon  its  use  in  the  program.  A  symbol 
in  the  operator  field  may  be  any  one  of  the  three  symbol  types.  To 
determine  the  value  of  the  symbol,  the  assembler  searches  the  three 
symbol  tables  in  the  following  order: 

1.  Macro  Symbol  Table 

2.  Permanent  Symbol  Table 

.  User-Defined  Symbol  Table 
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A  symbol  found  in  the  operand  field  is  sought  in  the: 

1.  User-Defined  Symbol  Table 

2.  Permanent  Symbol  Table 

in  that  order.  The  assembler  never  expects  to  find  a  macro  name  in  am 
operand  field. 

These  search  orders  allow  redefinition  of  Permanent  Symbol  Table 
entries  as  user-defined  or  macro  symbols.  The  same  name  can  be 
assigned  to  both  a  macro  and  a  label. 

User-defined  symbols  are  either  internal  or  external  (global) .  All 
user-defined  symbols  are  internal  unless  explicitly  defined  as  being 
global  with  the  . GLOBL  directive  (see  Section  5.5.10). 

Global  symbols  provide  links  between  object  modules.  A  global  symbol 
is  defined  as  a  label  is  generally  called  an  entry  point  (to  a  section 
of  code) .  Such  symbols  are  referenced  from  other  object  modules  to 
transfer  control  throughout  the  load  module  (which  may  be  composed  of 
a  number  of  object  modules) . 

Since  MACRO  provides  program  sectioning  capabilities  (Section  5.5.9)  , 
two  types  of  internal  symbols  must  be  considered: 

1.  Symbols  that  belong  to  the  current  program  section,  and 

2.  Symbols  that  belong  to  other  program  sections. 

In  both  cases,  the  symbol  must  be  defined  within  the  current  assembly; 
the  significance  of  the  distinction  is  critical  in  evaluating 
expressions  involving  type  (2)  above  (see  Section  5.2.9.) 


5.2.3  Direct  Assignment 


A  direct  assignment  statement  associates  a  symbol  with  a  value.  When 
a  direct  assignment  statement  defines  a  symbol  for  the  first  time, 
that  symbol  is  entered  into  the  user  symbol  table  and  the  specified 
value  is  associated  with  it.  A  symbol  may  be  redefined  by  assigning  a 
new  value  to  a  previously  defined  symbol.  The  latest  assigned  value 
replaces  any  previous  value  assigned  to  a  symbol. 


The  general  format  for  a  direct  assignment  statement  is : 


symbol  =  expression 


Symbols  take  on  the  relocatable  or  absolute  attribute  of  their 
defining  expression.  However,  if  the  defining  expression  is  global, 
the  symbol  is  not  global  unless  explicitly  defined  as  such  in  a  .GLOBL 
directive.  For  example: 

)  THE  SYMBOL  *  IS  EQUATEO  TO  THE 
I VALUE  I 


8a*A«l*MASKL0W  ITHE  SYMBOL  B  IS  EQUATEO  TO  TME 
I  VALUE  OP  THE  EXPRESSION 


Cl  0*3 


ITHE  SYMBOL  0  IS  EQUATED  TO  3 
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**  M0V  I  LABELS  C  AND  E  ARE  EQUATED  TO  THE 

I  LOCATION  OR  THE  MOV  COMMAND 

The  following  conventions  apply  to  direct  assignment  statements: 

1.  An  equal  sign  (=)  must  separate  the  symbol  from  the 

expression  defining  the  symbol  value. 

2.  A  direct  assignment  statement  is  usually  placed  in  the 
operator  field  and  may  be  preceded  by  a  label  and  followed  by 
a  comment. 


NOTE 

If  the  program  jumps  to  or  references 
the  label  of  a  direct  assignment 
statement,  it  is  actually  referencing 
the  following  instruction  statement. 
For  example: 

.•.♦1000 

Cl  D»3 

El  MOV  #0. ABLE 

JMP  C 

This  code  causes  a  jump  to  the  label  E. 


3.  Only  one  symbol  can  be  defined  by  any  one  direct  assignment 
statement. 

4.  Only  one  level  of  forward  referencing  is  allowed.  That  is, 
the  following  arrangement  is  illegals 

X  =  Y 

Y  =  Z 

Z  =  1 

X  and  Y  are  both  undefined  throughout  pass  1.  X  is  undefined 
throughout  pass  2  and  causes  an  error  flag  in  the  assembly 
listing. 


5.2.4  Register  Symbols 

The  eight  general  registers  of  the  PDP-11  are  numbered  0  through  7  and 
can  be  expressed  in  the  source  program  as: 

%0 

%1 


%7 
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The  digit  indicating  the  specific  register  can  be  replaced  by  any 
legal  term  which  can  be  evaluated  during  the  first  assembly  pass. 

It  is  recommended  that  the  programmer  create  and  use  symbolic  names 
for  all  register  references.  A  register  symbol  may  be  defined  in  a 
direct  assignment  statement  among  the  first  statements  in  the  program. 
A  register  symbol  cannot  be  defined  after  the  statement  which  uses  it. 
The  defining  expression  of  a  register  symbol  must  be  absolute.  For 
example  s 

R0.X0  REGISTER  DEFINITION 

R1"%1 

R2»X2 

RMS 

R4*X4 

R5»X5 

SP*Xfe 

FC»X7 

The  symbolic  names  assigned  to  the  registers  in  the  example  above  are 
the  conventional  names  used  in  all  PDP-11  system  programs.  Since 
these  names  are  fairly  mnemonic,  it  is  suggested  the  user  follow  this 
convention.  Registers  6  and  7  are  given  special  names  because  of 
their  special  functions,  while  registers  0  through  5  are  given  similar 
names  to  denote  their  status  as  general  purpose  registers. 

All  register  symbols  must  be  defined  before  they  are  referenced.  A 
forward  reference  to  a  register  symbol  causes  phase  errors  in  an 
assembly. 

The  %  character  can  be  used  with  any  term  or  expression  to  specify  a 
register.  (A  register  expression  less  than  0  or  greater  than  7  is 
flagged  with  an  R  error  code.)  For  example: 

CLR  X3*l 

is  equivalent  to: 

CLR  X4 

and  clears  the  contents  of  register  4,  while: 

CLR  4 

clears  the  contents  of  memory  address  4. 

In  certain  cases  a  register  can  be  referenced  without  the  use  of  a 
register  symbol  or  register  expression;  these  cases  are  recognized 
through  the  context  of  the  statement.  An  example  is  shown  below: 

JSR  5* SUBR  IFIR8T  OPERAND  FIELD  MUST  ALWAYS 

I  BE  A  REGISTER 


5.2.5  Local  Symbols 

Local  symbols  are  specially  formatted  symbols  used  as  labels  within  a 
given  range. 
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Local  symbols  provide  a  convenient  means  of  generating  labels  to  be 
referenced  by  branch  instructions.  Use  of  local  symbols  reduces  the 
possibility  of  multiply-defined  symbols  within  a  user  program  and 
separates  entry  point  symbols  from  local  references.  Local  symbols , 
then,  are  not  referenced  from  other  object  modules  or  even  from 
outside  their  local  symbol  block. 

Local  symbols  are  of  the  form  n$,  where  n  is  a  decimal  integer  from  1 
to  127,  inclusive,  and  can  only  be  used  on  word  boundaries.  Local 
symbols  include: 

1$ 

27$ 

59$ 

104$ 

Within  a  local  symbol  block,  local  symbols  can  be  defined  and 
referenced.  However,  a  local  symbol  cannot  be  referenced  outside  the 
block  in  which  it  is  defined.  There  is  no  conflict  with  labels  of  the 
same  name  in  other  local  symbol  blocks. 

Local  symbols  64$  through  127$  can  be  generated  automatically  as  a 
feature  of  the  macro  processor  (see  Section  5.6. 3.5  for  further 
details) .  When  using  local  symbols  the  user  is  advised  to  first  use 
the  range  from  1$  to  63$. 

A  local  symbol  block  is  delimited  in  one  of  the  following  ways: 

1.  The  range  of  a  single  local  symbol  block  can  consist  of  those 
statements  between  two  normally  constructed  symbolic  labels. 
(Note  that  a  statement  of  the  form: 

LABEL=. 

is  a  direct  assignment,  does  not  create  a  label  in  the  strict 
sense,  and  does  not  delimit  a  local  range.) 

2.  The  range  of  a  local  symbol  block  is  terminated  upon 
encountering  a  .CSECT  directive. 

3.  The  range  of  a  single  local  symbol  block  can  be  delimited 

with  .ENABL  LSB  and  the  first  symbolic  label  or  .CSECT 

directive  following  the  .DSABL  LSB  directives.  The  default 
for  LSB  is  off. 

For  examples  of  local  symbols  and  local  symbol  blocks,  see  Figure  5-1. 

The  maximum  offset  of  a  local  symbol  from  the  base  of  its  local  symbol 
block  is  128  decimal  words.  Symbols  beyond  this  range  are  flagged 
with  an  A  error  code. 
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5.2.6  Assembly  Location  Counter 

The  period  (.)  is  the  symbol  for  the  assembly  location  counter.  When 
used  in  the  operand  field  of  an  instruction,  it  represents  the  address 
of  the  first  word  of  the  instruction.  When  used  in  the  operand  field 
of  an  assembler  directive,  it  represents  the  address  of  the  current 
byte  or  word.  For  example: 

A«  MOV  *.,R0  |a  REFERS  TO  LOCATION  A, 

f I  •  E  9 1  THE  ADDRESS  OF  THE 
I  MOV  INSTRUCTION 


(#  is  explained  in  Section  5.4.9). 


At  the  beginning  of  each  assembly  pass,  the  assembler  clears  the 
location  counter.  Normally,  consecutive  memory  locations  are  assigned 
to  each  byte  of  object  data  generated.  However,  the  location  where 
the  object  data  is  stored  may  be  changed  by  a  direct  assignment 
statement  altering  the  location  counter: 

.=expression 

The  expression  defining  the  location  counter  must  not  contain  forward 
references  or  symbols  that  vary  from  one  pass  to  another.  If  an 
expression  is  assigned  to  the  current  location  counter  in  a 
relocatable  CSECT,  an  error  flag  is  generated.  (The  construction 
•=.+expression  must  be  used.) 

Similar  to  other  symbols,  the  location  counter  symbol  has  a  mode 
associated  with  it,  either  absolute  or  relocatable;  the  mode  cannot 
be  external.  The  existing  mode  of  the  location  counter  cannot  be 
changed  by  using  a  defining  expression  of  a  different  mode. 
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Line  Octal 

Number  Expansion  Source  Code  Comments 


1 

2 

3 

4 


5 


6 

r  i 

0  i 

9 

10 

000000 

000000 

000000 

.MCALL 

.REGOEP 

..V2., 

R0aX0 

.sbttl 

, RESDEF , *  * V2» , 

SECTOR  INITIALIZATION 

11 

12 

13 

14 

00000 

00000 

000000  * 

IMPURE  1 

000000  * 

IMPPASl 

•CSECT 

IMPURE 

.CSECT  IMPPA3 

IIMPURE  STORAGE  AREA 

7CLEARE0  EACH  PASS 

15 

16 

00000 

000000* 

IMPLINI 

.C8ECT 

IMPLIN 

f CLEARED  EACH  LINE 

17 

18 
19 

00000 

000000* 

XCTPRGI 

•CSECT 

XCTPRG 

IPROGRAM 

iinitialization 

20 

00000 

012700 

000000* 

MOV 

PIMPURE  t R0 

21 

00004 

005020  1SI 

CLR 

(R0)  ♦ 

ICLEAR  IMPURE  AREA 

22 

00006 

022700 

000000* 

CMP 

#IMPTOP,R0 

23 

24 

00012 

101374 

BHI 

IS 

25 

26 

00000 

000000* 

XCTPA8I 

•CSECT 

XCTPAS 

7PASS  INITIALIZATION 

27 

00000 

012700 

000000* 

MOV 

#IMPPAS,R0 

26 

00004 

005020  1SI 

CUR 

(R0)  + 

ICLEAR  IMPURE  PART 

29 

00006 

022700 

000000* 

CMP 

#IMPTOP,R0 

30 

31 

00012 

101374 

BHI 

IS 

32 

33 

00000 

000000* 

XCTLINI 

•CSECT 

XCTLIN 

ILINE  INITIALIZATION 

34 

00000 

012700 

000000* 

MOV 

#IMPLXN,R0 

35 

00004 

005020  1  SI 

CLR 

(R0)  + 

36 

00006 

022700 

000000* 

CMP 

•IMPTOP,R0 

37 

38 

00012 

101374 

BHI 

IS 

39 

40 

41 

00000 

000000* 

000000  IMPTOPI 
000001* 

.CSECT 
.WORD  0 
,EN0 

MIXED 

f MIXED  MOOE  SECTOR 

Figure  5-1 

Assembly  Source  Listing  of  MACRO  Code  Showing  Local  Symbol  Blocks 
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The  mode  of  the  location  counter  symbol  can  be  changed  by  the  use  of 
the  .ASECT  or  .CSECT  directive  as  explained  in  Section  5.5.9. 

Examples : 


.A8ECT 


,■500  >  SET  LOCATION  COUNTER  TO 

> ABSOLUTE  900 

FIRST!  MOV  ,*10, COUNT  >THE  LABEL  FIRST  HAS  THE  VALUE 

1500(6) 

>,♦10  EQUALS  510(6),  THE 
ICONTENTS  OF  THE  LOCATION 
>510(8)  WILL  BE  DEPOSITED 
>IN  LOCATION  COUNT, 

> THE  ASSEMBLY  LOCATION  COUNTER 
> NOW  HAS  A  VALUE  OF 
> ABSOLUTE  520(8). 

>THE  LABEL  SECOND  HAS  THE 
> VALUE  520(8) 

> THE  CONTENTS  OF  LOCATION 
>520(8),  THAT  IS,  THE  BINARY 
> CODE  FOR  THE  INSTRUCTION 
> ITSELF  WILL  BE  DEPOSITED  IN 
> LOCATION  INDEX, 


> SET  LOCATION  COUNTER  TO 
RELOCATABLE  20  OF  THE 
> UNNAMED  PROGRAM  SECTION, 

) THE  LABEL  THIRD  HAS  THE 
> VALUE  OF  RELOCATABLE  20, 

Storage  area  may  be  reserved  by  advancing  the  location  counter.  For 
example,  if  the  current  value  of  the  location  counter  is  1000,  the 
direct  assignment  statement: 

,*,*100 

reserves  100 (octal)  bytes  of  storage  space  in  the  program.  The  next 
instruction  is  stored  at  1100.  (The  .BLKW  and  .BLKB  directives  can 
also  be  used  to  reserve  blocks  of  storage;  see  Section  5. 5. 5. 3.) 


COUNT!  , WORD  0 
,■520 

SECOND  I  MOV  ,, INDEX 

INDEX!  .WORD  0 

,C»ECT 

,■,♦20 

THIRD!  .WORD  0 
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5.2.7  Numbers 


The  MACRO  Assembler  assumes  all  numbers  in  the  source  program  are  to 
be  interpreted  in  octal  radix  unless  otherwise  specified.  The  assumed 
radix  can  be  altered  with  the  .RADIX  directive  or  individual  numbers 
can  be  treated  as  being  of  decimal,  binary,  or  octal  radix  (see 
Section  5. 5. 4. 2). 

Octal  numbers  consist  of  the  digits  0  through  7  only.  A  number  not 
specified  as  a  decimal  number  and  containing  an  8  or  9  is  flagged  with 
an  N  error  code  and  treated  as  a  decimal  number. 

Negative  numbers  are  preceded  by  a  minus  sign  (the  assembler 
translates  them  into  two's  complement  form) .  Positive  numbers  may  be 
preceded  by  a  plus  sign,  although  this  is  not  required. 

A  number  which  is  too  large  to  fit  into  16  bits  (177777<n)  is 
truncated  from  the  left  and  flagged  with  a  T  error  code  in  the 
assembly  listing. 

Numbers  are  always  considered  absolute  quantities  (that  is,  not 
relocatable) . 


The  single-word  floating-point  numbers  which  can  be  generated  with  the 
tF  operator  (see  Section  5. 5. 6. 2)  are  stored  in  the  following  formats 


15  14 


6 


0 


SIGN 

BIT 


8- BIT  EXPONENT 


7-BIT  MANTISSA 


Refer  to  PDP-11/45  PROCESSOR  HANDBOOK  for  details  of  the 
floating-point  format. 


5.2.8  Terms 

A  term  is  a  component  of  an  expression.  A  term  may  be  one  of  the 
followings 

1.  A  number  whose  16-bit  value  is  used. 

2.  A  symbol  that  is  interpreted  according  to  the  following 

hierarchy  s 

a.  a  period  that  causes  the  value  of  the  current  location 
counter  to  be  used 

b.  a  permanent  symbol  whose  basic  value  is  used  and  whose 
arguments  (if  any)  are  ignored 

c.  user  defined  symbols 

d.  an  undefined  symbol  that  is  assigned  a  value  of  zero  and 
inserted  in  the  user-defined  symbol  table 
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3.  An  ASCII  conversion  using  either  an  apostrophe  followed  by  a 
single  ASCII  character  or  a  double  quote  followed  by  two 
ASCII  characters,  which  results  in  a  word  containing  the 
7-bit  ASCII  value  of  the  character (s) .  (This  construction  is 
explained  in  greater  detail  in  Section  5. 5. 3. 3.) 

4.  An  expression  enclosed  in  angle  brackets.  Any  quantity 
enclosed  in  angle  brackets  is  evaluated  before  the  remainder 
of  the  expression  in  which  it  is  found.  Angle  brackets  are 
used  to  alter  the  left  to  right  evaluation  of  expressions 
(for  example,  to  differentiate  between  A*B+C  and  A*<B+C>)  or 
to  apply  a  unary  operator  to  an  entire  expression  (-<A+B>). 


5.2.9  Expressions 

Expressions  are  combinations  of  terms  that  are  joined  together  by 
binary  operators  and  that  reduce  to  a  16-bit  value.  The  operands  of  a 
.BYTE  directive  are  evaluated  as  word  expressions  before  truncation  to 
the  low-order  eight  bits.  Prior  to  truncation,  the  high-order  byte 
must  be  zero  or  all  ones  (when  the  byte  value  is  negative,  the  sign 
bit  is  propagated) .  The  evaluation  of  an  expression  includes  the 
evaluation  of  the  mode  of  the  resultant  expression — that  is,  absolute, 
relocatable  or  external.  Expression  modes  are  defined  further  below. 

Expressions  are  evaluated  left  to  right  with  no  operator  hierarchy 
rules  except  that  unary  operators  take  precedence  over  binary 
operators.  A  term  preceded  by  a  unary  operator  can  be  considered  as 
containing  that  unary  operator.  (Terms  are  evaluated,  where 
necessary,  before  their  use  in  expressions.)  Multiple  unary  operators 
are  valid  and  are  treated  as  follows: 


— +— A 

is  equivalent  to: 

-<+<-A>> 

The  value  of  an  external  expression  is  the  value  of  the  absolute  part 
of  the  expression;  e.g.,  EXT+A  has  a  value  of  A.  This  is  modified  by 
the  Linker  to  become  EXT+A. 

Expressions,  when  evaluated,  are  either  absolute,  relocatable,  or 
external.  For  the  programmer  writing  position  independent  code,  the 
distinction  is  important. 

1.  An  expression  is  absolute  if  its  value  is  fixed.  An 

expression  whose  terms  are  numbers  and  ASCII  conversions  has 
an  absolute  value.  A  relocatable  expression  minus  a 
relocatable  term,  where  both  items  belong  to  the  same  program 
section,  is  also  absolute. 

2.  An  expression  is  relocatable  if  its  value  is  fixed  relative 
to  a  base  address  but  will  have  an  offset  value  added  when 
linked.  Expressions  whose  terms  contain  labels  defined  in 
relocatable  sections  and  the  assembly  location  counter  (in 
relocatable  sections)  have  a  relocatable  value. 

An  expression  is  external  (or  global)  if  its  value  is  only 
partially  defined  during  assembly  and  is  completed  at  link 
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time.  An  expression  whose  terms  contain  a  global  symbol  not 
defined  in  the  current  program  is  an  external  expression. 
External  expressions  have  relocatable  values  at  execution 
time  if  the  global  symbol  is  defined  as  being  relocatable  or 
absolute  if  the  global  symbol  is  defined  as  absolute. 

An  example  of  the  three  expression  types  follows: 


.ASECT 

.•100 

ABSSYMs, 

ITHE  VALUE  OF  AB8SVM  IS 

1  NOT  RELOCATABLE,  BECAUSE 

IWE  ARE  IN  AN  ASECT 

,  CSECT  MAIN 

ISTART  RELOCATABLE 

1  PROGRAM  SECTION 

•GLOBL  EXTVAL 

1 EXTVAL  IS  DEFINED  ELSEWHERE t 
1  ITS  VALUE  WILL  NOT  BE  KNOWN 

1  UNTIL  LINK  TIME 

BEGSYMI  .SLKW  *» 

.ASCII  / ABCD/ 

.EVEN 

ENDSYMa, 

1  THE  VALUES  OF  BEGSYM 

1 AND  ENDS YM  ARE 

I  RELOCATABLE,  BECAUSE 

ITHE  ADDRESS  AT  WHICH 

1 "  M  A I N  H  WILL  BE  L0ADE0 

IIS  NOT  DETERMINED  UNTIL 

RINK  TIME 

SIZE  •  endsym-begsym 

IHOWEVER,  THE 

1  VALUE  OF  SIZE  IS  KNOWN 

ICIT  IS  1 2 . ) A T  ASSEMBLY 

1  TIME  AND  IS  ABSOLUTE 

RELEXP  b  ENDSYM-BEGSYM*. 

IRELEXP  (a. *12.)  IS 
{RELOCATABLE 

EXTEXPI  .W0R0  EXTVAL*** 

ITHE  EXPRESSION  "EXTVAL***" 

IIS  EXTERNAL  (OR  GLOBAL) 

1  BECAUSE  EXTVAL  IS  DEFINED 

1  IN  another  program  unit. 

CHARAs  *A 

ITHE  VALUE  OF  CHARA 

IIS  absolute 

5.3  RELOCATION  AND  LINKING 

The  output  of  the  MACRO  Assembler  is  an  object  module  which  must  be 
processed  by  LINK  before  loading  and  execution  (refer  to  Chapter  6  for 
details).  The  Linker  essentially  fixes  (i.e.,  makes  absolute)  the 
values  of  external  or  relocatable  symbols  and  turns  the  object  module 
into  a  load  module. 

To  enable  the  Linker  to  fix  the  value  of  an  expression ,  the  assembler 
issues  certain  directives  to  the  Linker  together  with  required 
parameters.  In  the  case  of  relocatable  expressions ,  the  Linker  adds 
the  base  of  the  associated  relocatable  section  (the  location  in  memory 
of  relocatable  0)  to  the  value  of  the  relocatable  expression  provided 
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by  the  assembler.  In  the  case  of  an  external  expression,  the  value  of 
the  external  term  in  the  expression  is  determined  by  the  Linker  (since 
the  external  symbol  must  be  defined  in  one  of  the  other  object  modules 
which  are  being  linked  together)  and  adds  it  to  the  value  of  the 
external  expression  provided  by  the  assembler. 

All  words  that  are  to  be  modified  (as  described  in  the  previous 
paragraph)  are  marked  with  an  apostrophe  in  the  assembly  listing.  A  G 
in  the  listing  indicates  that  the  value  is  external,  or  that  a  global 


is  added 
follows : 

to  that 

value.  Thus,  the  binary  text  output  looks  as 

005065 

000000C 

CLR 

EXTERNAL (R5) 

1  VALUE  OF  EXTERNAL  SYMBOL 

I  ASSEMBLED  ZERO;  MILL  BE 
f MODIFIED  BY  THE  LINKER, 

005065 

000006C 

CLR 

EXTERNAL*6(R5) 

ITHE  ABSOLUTE  PORTION  OF  THE 

1  EXPRESSION  (000006)  IS  AD0E0 
IBY  THE  LINKER  TO  THE  VALUE  OF 
ITHE  EXTERNAL  SYMBOL 

005065 

CLR 

RELOCATABLE(RS) 

1  ASSUMING  WE  ARE  IN  A 

000040 

I  RELOCATABLE  SECTION 
I  AND  THE  VALUE  OF  RELOCATABLE 
IIS  RELOCATABLE  40 


5.4  ADDRESSING  MODES 

The  program  counter  (PC,  register  7  of  the  eight  general  registers) 
always  contains  the  address  of  the  next  word  to  be  fetched;  i.e.,  the 
address  of  the  next  instruction  to  be  executed,  or  the  second  or  third 
word  of  the  current  instruction. 

In  order  to  understand  how  the  address  modes  operate  and  how  they 
assemble,  the  action  of  the  program  counter  must  be  understood.  The 
key  rule  is : 

Whenever  the  processor  implicitly  uses  the  program  counter 
to  fetch  a  word  from  memory,  the  program  counter  is 
automatically  incremented  by  two  after  the  fetch. 

That  is,  when  an  instruction  is  fetched,  the  PC  is  incremented  by  two 
so  that  it  is  pointing  to  the  next  word  in  memory;  if  an  instruction 
uses  indexing  (Sections  5.4.7,  5.4.9  and  5.4.11)  the  processor  uses 
the  program  counter  to  fetch  the  base  from  memory.  Hence,  using  the 
rule  above,  the  PC  increments  by  two,  and  now  points  to  the  next  word. 

The  following  conventions  are  used  in  this  section: 

1.  Let  E  be'  any  expression  as  defined  in  Section  5.2. 

2.  Let  R  be  a  register  expression.  This  is  any  expression 
containing  a  term  preceded  by  a  %  character  or  a  symbol 
previously  equated  to  such  a  term. 
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Examples : 

R0«X0  I  GENERAL  REGISTER  0 
R1«R0*1  I  GENERAL  REGISTER  1 
R2M+XI  ? GENERAL  REGISTER  2 

3.  Let  ER  be  a  register  expression  or  an  expression  in  the  range 
0  to  7  inclusive. 

4.  Let  A  be  any  general  address  specification  which  produces  a 
6-bit  mode  address  field  as  described  in  Sections  3.1  and  3.2 
of  the  PDP-11  PROCESSOR  HANDBOOK  (both  11/20  and  11/45 
versions) . 

The  addressing  specifications.  A,  can  be  explained  in  terms  of  E,  R, 
and  ER  as  defined  above.  Each  is  illustrated  with  the  single  operand 
instruction  CLR  or  double  operand  instruction  MOV. 


5.4.1  Register  Mode 
The  register  contains  the  operand. 
Format  for  A:  R 

Examples:  R0aX0 

CL*  R0 


IDEFINE  R0  AS  REGISTER  0 
ICLEAR  REGISTER  0 


5.4.2  Register  Deferred  Mode 

The  register  contains  the  address  of  the  operand. 


Format  for  A: 

@R  or 

(ER) 

Examples  s 

CUN 

RR1 

IBOTH  INSTRUCTIONS  CLEAR 
ITHE  WORD  AT  THE  ADDRESS 

CL* 

(Rl) 

IC0NTAINE0  IN  REGISTER  | 

5.4.3  Autoincrement  Mode 


The  contents  of  the  register  are  incremented  immediately  after  being 
used  as  the  address  of  the  operand.  (See  NOTE  below.) 
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Format  for  A:  (ER)  + 


Examples : 


tin  (RPl)  ♦  JEACH  INSTRUCTION  CLEARS 

tin  (R0*3)*  ITHE  WORD  AT  THE  ADDRESS 
CLR  (R2)*  ICONTAINED  IN  THE  SPECIFIED 
f REGISTER  AND  INCREMENTS 
f THAT  REGISTERS  CONTENTS 
I  BY  TWO, 


CLNB  (R4)4  ICLEARS  THE  BYTE  AT  THE 

MOORESS  SPECIFIED  BY  THE 
^CONTENTS  OF  R4  AND 
IINCREMENTS  R4  BY  ONE, 


NOTE 

Both  JMP  and  JSR  instructions  using 
non-def erred  autoincrement  mode, 
autoincrement  the  register  before  its 
use  on  the  PDP-11/20  and  11/05  (but  not 
on  the  PDP-11/40  or  11/45) .  In  double 
operand  instructions  of  the  addressing 
form  %R, (R)+  or  %R,-(R)  where  the  source 
and  destination  registers  are  the  same, 
the  source  operand  is  evaluated  as  the 
autoincremented  or  autodecremented 
value,  but  the  destination  register,  at 
the  time  it  is  used,  still  contains  the 
originally  intended  effective  address. 


In  the  following  two  examples,  as 
executed  on  the  PDP-11/20,  R0  originally 


contains 

100. 

MOV 

R0, (R0)* 

1  THE  QUANTITY  10?  15  MOVED 
1  TO  LOCATION  100 

MOV 

R0, • (R0) 

t THE  QUANTITY  76  IS  MOVED 
|T0  LOCATION  76 

The  use  of  these  forms  should  be  avoided 
as  they  are  not  compatible  with  the 
PDP-11/05,  11/40  and  11/45. 

A  Z  error  code  is  printed  with  each  instruction  which  is  not 
compatible  among  all  members  of  the  PDP-11  family.  This  is  merely  a 
warning  code. 


5.4.4  Autoincrement  Deferred  Mode 

The  register  contains  the  pointer  to  the  address  of  the  operand.  The 
contents  of  the  register  are  incremented  after  being  used. 
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Format  for  A:  Q(FR)  + 

Example:  CL*  P(B3)*  'CONTENTS  OF  REGISTER  3  POINT 

»T0  ADDRESS  OF  WORD  TO  BE 
f CLEARED*  AND  REGISTER  3  IS 
' THEN  INCREMENTED  BY  TWO 


5.4.5  Autodecrement  Mode 

The  contents  of  the  register  are  decremented  before  being  used  as  the 
address  of  the  operand  (see  NOTE  under  autoincrement  mode) . 

Format  for  A:  -(ER) 

Examples:  CL*  *CR0)  'DECREMENT  CONTENTS  OF 

CL*  • (R0*3)  >0,  3,  AND  2  BY  TWO 

CL*  *CR2)  ' BEFORE  USING  AS  ADDRESSES 

'  OF  WORDS  TO  BE  CLEARED. 


5.4.6  Autodecrement  Deferred  Mode 

The  contents  of  the  register  are  decremented  before  being  used  as  the 
pointer  to  the  address  of  the  operand. 

Format  for  A:  @-(ER) 

Example:  CL*  M(R2)  IDECREMENT  CONTENTS  OF 

'REGISTER  2  By  TWO  BEFORE 
'USING  AS  A  POINTER 
'TO  ADDRESS  OF  WORD  TO  BE 
'CLEARED. 


5.4.7  Index  Mode 

The  value  of  an  expression  E  is  stored  as  the  second  or  third  word  of 
the  instruction.  The  effective  address  is  calculated  as  the  value  of 
E  plus  the  contents  of  register  ER.  The  value  E  is  called  the  base. 

Format  for  A:  E (ER) 

Examples:  CL*  X*2lRi)  'EFFECTIVE  AD0RES3  IS  X+g  PLUS 

'THE  CONTENTS  OF  REGISTER  1 
CL*  *2(R3)  'EFFECTIVE  ADDRESS  IS  *2  PLUS 
'THE  CONTENTS  OF  REGISTER  3. 


5.4.8  Index  Deferred  Mode 

An  expression  plus  the  contents  of  a  register  gives  the  pointer  to  the 
address  of  the  operand. 
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Format  for  A:  @E(ER) 

Example:  ClR  #14(R4)  |I F  REGISTER  4  HOLDS  100  AND 

| LOC  114  HOLDS  2000, 
JLOCATION  8000  IS  CLEARED. 


5.4.9  Immediate  Mode 

The  immediate  mode  allows  the  operand  itself  to  be  stored  as  the 
second  or  third  word  of  the  instruction.  It  is  assembled  as  an 
autoincrement  of  register  7,  the  PC. 

Format  for  A:  #E 

Examples:  HOT  #100, R0  JMOVE  AN  OCTAL  100  TO 

I  REGISTER  0 

MOV  «X,R0  IMOVE  THE  VALUE  OF  THE  SVMBOL  X  TO 
IREGISTER  0 

The  operation  of  this  mode  can  be  explained  by  the  following  example. 
The  statement  MOV  #100, R3  assembles  as  two  words.  These  are: 

012703 

000100 

Just  before  this  instruction  is  fetched  and  executed,  the  PC  points  to 
the  first  word  of  the  instruction.  The  processor  fetches  the  first 
word  and  increments  the  PC  by  two.  The  source  operand  mode  is  27 
(autoincrement  the  PC).  Thus,  the  PC  is  used  as  a  pointer  to  fetch  the 
operand  (the  second  word  of  the  instruction)  before  being  incremented 
by  two,  to  point  to  the  next  instruction. 


5.4.10  Absolute  Mode 

Absolute  mode  is  the  equivalent  of  immediate  mode  deferred.  @#E 
specifies  an  absolute  address  which  is  stored  in  the  second  or  third 
word  of  the  instruction.  Absolute  mode  is  assembled  as  an 
autoincrement  deferred  of  register  7,  the  PC. 


Format  for 

As 

@#E 

Examples  s 

MOV 

•#100, R0 

IMOVE  THE  VALUE  OF  CONTENTS 

1  OF  LOCATION  100  TO 

IREGISTER  0. 

CL* 

MX 

ICLEAR  THE  CONTENTS  OF  THE 
ILOCATION  WHOSE  ADDRESS  IS  X. 

5.4.11  Relative  Mode 

Relative  mode  is  the  normal  mode  for  memory  references. 
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Format  for  As  E 

Examples:  CL»  10ft  I  CLEAR  LOCATION  10ft 

MOV  X,Y  |M0V  THE  CONTENTS  OF  LOCATION  X 

I  TO  LOCATION  Y, 

Relative  mode  is  assembled  as  index  mode,  using  register  7,  the  PC,  as 
the  index  register.  The  base  of  the  address  calculation,  which  is 
stored  in  the  second  or  third  word  of  the  instruction,  is  not  the 
address  of  the  operand  (as  in  index  mode),  but  the  number  which,  when 
added  to  the  PC,  becomes  the  address  of  the  operand.  Thus,  the  base 
is  X— PC,  which  is  called  an  offset.  The  operation  is  explained  as 
follows : 

If  the  statement  MOV  100, R3  is  assembled  at  absolute  location  20,  the 
assembled  code  is : 

Location  20:  016703 

Location  22:  000054 

The  processor  fetches  the  MOV  instruction  and  adds  two  to  the  PC  so 
that  it  points  to  location  22.  The  source  operand  mode  is  67,  that  is, 
indexed  by  the  PC.  To  pick  up  the  base,  the  processor  fetches  the 
word  pointed  to  by  the  PC  and  adds  two  to  the  PC.  The  PC  now  points 
to  location  24.  To  calculate  the  address  of  the  source  operand,  the 
base  is  added  to  the  designated  register,  that  is,  BASE+PC=54+24=100, 
the  operand  address. 

Since  the  assembler  considers  as  the  address  of  the  first  word  of 
the  instruction,  an  equivalent  index  mode  statement  would  be: 

MOV  100-.-4 (PC) ,R3 

This  mode  is  called  relative  because  the  operand  address  is  calculated 
relative  to  the  current  PC.  The  base  is  the  distance  or  offset  (in 
bytes)  between  the  operand  and  the  current  PC.  If  the  operator  and 
its  operand  are  moved  in  memory  so  that  the  distance  between  the 
operator  and  data  remains  constant,  the  instruction  will  operate 
correctly  anywhere  in  memory. 


5.4.12  Relative  Deferred  Mode 

Relative  deferred  mode  is  similar  to  relative  mode,  except  that  the 
expression,  E,  is  used  as  the  pointer  to  the  address  of  the  operand. 

Format  for  A:  £)E 

Example:  MOV  #X,R0  |M0VE  THE  CONTENTS  OF  THE 

IL0CATX0N  WHOSE  ADDRESS  IS  IN 
fX  INTO  REGISTER  0 


5.4.13  Table  of  Mode  Forms  and  Codes 

Each  instruction  assembles  into  at  least  one  word.  Operands  of  the 
first  six  forms  listed  below  do  not  increase  the  length  of  an 
instruction.  Each  operand  in  one  of  the  other  modes,  however, 
increases  the  instruction  length  by  one  word. 
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Form 

Mode 

Meaning 

R 

On 

Register  mode 

@R  or  (ER) 

In 

Register  deferred  mode 

(ER)  + 

2n 

Autoincrement  mode 

@  (ER)  + 

3n 

Autoincrement  deferred  mode 

-(ER) 

4n 

Autodecrement  mode 

@-  (ER) 

5n 

Autodecrement  deferred  mode 

n  represents  the  register  number. 

Any  of  the  following  forms  adds  one  word  to  the  instruction  length: 


Form 

Mode 

Meaning 

E  (ER) 

6n 

Index  mode 

@E  (ER) 

7n 

Index  deferred  mode 

#E 

27 

Immediate  mode 

@#E 

37 

Absolute 

memory  reference  mode 

E 

67 

Relative 

mode 

@E 

77 

Relative 

deferred  reference  mo< 

n  represents  the  register  number.  Note  that  in  the  last  four  forms, 
register  7  (the  PC)  is  referenced. 

NOTE 


An  alternate  form  for  @R  is  (ER) . 
However,  the  form  @(ER)  is  equivalent  to 
@0  (ER)  . 

The  form  @#E  differs  from  the  form  E  in 
that  the  second  or  third  word  of  the 
instruction  contains  the  absolute 
address  of  the  operand  rather  than  the 
relative  distance  between  the  operand 
and  the  PC.  Thus,  the  instruction 
CIjR  @#100  clears  absolute  location  100 
even  if  the  instruction  is  moved  from 
the  point  at  which  it  was  assembled. 
See  the  description  of  the  .ENABL  AMA 
function  in  Section  5.5.2,  which  directs 
the  assembly  of  all  relative  mode 
addresses  as  absolute  mode  addresses. 


5.4.14  Branch  Instruction  Addressing 

The  branch  instructions  are  1-word  instructions.  The  high  byte 
contains  the  op  code  and  the  low  byte  contains  an  8-bit  signed  offset 
which  specifies  the  branch  address  relative  to  the  PC.  Upon  execution 
of  a  branch  instruction,  the  hardware  calculates  the  branch  address  as 
follows : 

1.  Extend  the  sign  of  the  offset  through  bits  8-15. 

2.  Multiply  the  result  by  2.  This  creates  a  word  offset  rather 
than  a  byte  offset. 
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3.  Add  the  result  to  the  PC  to  form  the  final  branch  address. 

The  assembler  performs  the  reverse  operation  to  form  the  byte  offset 
from  the  specified  address.  Remember  that  when  the  offset  is  added  to 
the  PC,  the  PC  is  pointing  to  the  word  following  the  branch 
instruction;  hence  the  term  -2  in  the  calculation. 

Byte  offset  =  (E-PC)/2  truncated  to  eight  bits. 

Since  PC  **  .+2,  we  have: 

Byte  offset  =  (E-.-2)/2  truncated  to  eight  bits. 

NOTE 

It  is  illegal  to  branch  to  a  location 
specified  as  an  external  symbol,  or  to  a 
relocatable  symbol  from  within  an 
absolute  section,  or  to  an  absolute 
symbol  or  a  relocatable  symbol  or 
another  program  section  from  within  a 
relocatable  section. 


5.4.15  EMT  and  TRAP  Addressing 

The  EMT  and  TRAP  instructions  do  not  use  the  low-order  byte  of  the 
word.  This  allows  information  to  be  transferred  to  the  trap  handlers 
in  the  low-order  byte.  If  EMT  or  TRAP  is  followed  by  an  expression, 
the  value  is  put  into  the  low-order  byte  of  the  word.  However,  if  the 
expression  is  too  big  (>377(8))  it  is  truncated  to  eight  bits  and  a  T 
error  flag  is  generated. 


5.5  ASSEMBLER  DIRECTIVES 

Directives  are  statements  which  cause  the  assembler  to  perform  certain 
processing  operations. 

Assembler  directives  can  be  preceded  by  a  label,  subject  to 
restrictions  associated  with  specific  directives,  and  followed  by  a 
comment.  An  assembler  directive  occupies  the  operator  field  of  a 
MACRO  source  line.  Only  one  directive  can  be  placed  on  any  one  line. 
Zero,  one,  or  more  operands  can  occupy  the  operand  field;  legal 
operands  differ  with  each  directive  and  may  be  either  symbols, 
expressions,  or  arguments. 


5.5.1  Listing  Control  Directives 


5. 5. 1.1  .LIST  and  .NLIST  -  Listing  options  can  be  specified  in  the 
text  of  a  MACRO  program  through  the  .LIST  and  .NLIST  directives. 
These  are  of  the  form: 

.LIST  arg 
.NLIST  arg 
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where  arg  represents  one  or  more  optional  arguments.  When  used 
without  arguments,  the  listing  directives  alter  the  listing  level 
count.  The  listing  level  count  causes  the  listing  to  be  suppressed 
when  it  is  negative.  The  count  is  initialized  to  zero,  incremented 
for  each  .LIST  and  decremented  for  each  .NLIST.  For  example: 


.LIST  HE 

.MACRO  LTEST  ILIST  TEST 
M-THIS  LINE  SHOULD  LIST 
.NLIST 

I8-THI3  LINE  SHOULD  NOT  LIST 
.NLIST 

IC-THIS  LINE  SHOULD  NOT  LIST 
.LIST 

I0*THIS  LINE  SHOULD  NOT  LIST  (LEVEL  NOT  BACK  TO  ZERO) 

.LIST 

f E«THIS  LINE  SHOULD  LIST  (LEVEL  BACK  TO  ZERO) 

.endm 

LTfeST  icall  the  macro 

|A»THIS  LINE  SHOULD  LIST 

|E*THIS  LINE  SHOULO  LIST  (LEVEL  BACK  TO  ZERO) 

The  primary  purpose  of  the  level  count  is  to  allow  macro  expansions  to 
be  selectively  listed  and  yet  exit  with  the  level  returned  to  the 
status  current  during  the  macro  call. 

The  use  of  arguments  with  the  listing  directives  does  not  affect  the 
level  count;  however,  .LIST  and  .NLIST  can  be  used  to  override  the 
current  listing  control.  For  example: 

.MACRO  XX 


.LIST  I  LIST  NEXT  LINE 

X-. 

.NLIST  IDO  NOT  LIST  REMAINDER 

ior  macro  expansion 


.ENDM 

.NLIST  ME  100  NOT  LIST  MACRO  EXPANSIONS 

XX 

X". 


Allowable  arguments  for  use  with  the  listing  directives  are  as  follows 
(these  arguments  can  be  used  singly  or  in  combination) : 


Argument 

Default 

Function 

SEQ 

list 

Controls  the  listing 
sequence  numbers. 

of 

source  line 

LOC 

list 

Controls  the  listing  of 
counter  (this  field  would 
be  suppressed) . 

the  location 
not  normally 

BIN 

list 

Controls  the  listing  of 
code  (supersedes  BEX) • 

generated  binary 
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BEX 


SRC 

COM 


MD 


MC 


ME 


MEB 


CND 


LD 


TOC 


TTM 


SYM 


list 

list 

list 

list 

list 

no  list 

no  list 


list 


no  list 


list 


Teletype 

mode 


list 


Controls  listing  of  binary  extensions; 
that  is,  prevents  listing  those 
locations  and  binary  contents  beyond  the 
first  line  of  an  expansion.  This  is  a 
subset  of  the  BIN  argument. 

Controls  the  listing  of  the  source  code. 

Controls  the  listing  of  comments.  This 
is  a  subset  of  the  SRC  argument  and  can 
be  used  to  reduce  listing  time  and/or 
space  where  comments  are  unnecessary. 

Controls  listing  of  macro  definitions 
and  repeat  range  expansions  (has  no 
effect  in  ASEMBL) . 

Controls  listing  of  macro  calls  and 
repeat  range  expansions  (has  no  effect 
in  ASEMBL) . 

Controls  listing  of  macro  expansions 
(supersedes  MEB;  has  no  effect  in 
ASEMBL)  . 

Controls  listing  of  macro  expansion 
binary  code.  A  .LIST  MEB  causes  only 
those  macro  expansion  statements 
producing  binary  code  to  be  listed. 
This  is  a  subset  of  the  ME  argument  (has 
no  effect  in  ASEMBL) . 

Controls  the  listing  of  unsatisfied 
conditions  and  all  .IF  and  .ENDC 
statements.  This  argument  permits 
conditional  assemblies  to  be  listed 
without  including  unsatisfied  code. 

Controls  listing  of  all  listing 
directives  having  no  arguments  (those 
used  to  alter  the  listing  level  count) • 

Controls  listing  of  table  of  contents  on 
pass  1  of  the  assembly  (see  Section 
5. 5. 1.4  describing  the  . SBTTL 
directive) .  The  full  assembly  listing  is 
printed  during  pass  2  of  the  assembly. 

Controls  listing  output  format  (has  no 
effect  in  ASEMBL) .  The  TTM  argument  (the 
default  case)  causes  output  lines  to  be 
truncated  to  72  characters.  Binary  code 
is  printed  with  the  binary  extensions 
below  the  first  binary  word.  The 
alternative  (.NLIST  TTM)  to  Terminal 
mode  is  line  printer  mode,  which  is 
shown  in  Figure  5-2. 

Controls  the  listing  of  the  symbol  table 
for  the  assembly. 
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An  example  of  an  assembly  listing  as  sent  to  a  132-column  line  printer 
is  shown  in  Figure  5-2.  Notice  that  binary  extensions  for  statements 
generating  more  than  one  word  are  spread  horizontally  on  the  source 
line.  An  example  of  an  assembly  listing  as  sent  to  an  80-column  line 
printer  is  shown  in  Figure  5-3  (this  is  the  same  format  as  a  terminal 
listing) .  Notice  that  binary  extensions  for  statements  generating  more 
than  one  word  are  printed  on  subsequent  lines. 

Figure  5-4  illustrates  a  symbol  table  listing.  With  the  exception  of 
local  symbols  and  macro  names,  all  user-defined  symbols  are  listed  in 
the  symbol  table.  The  characters  following  the  symbols  listed  have 
special  meanings  as  follows : 

=  the  symbol  is  assigned  in  a  direct  assignment 

statement 

%  the  symbol  is  a  register  symbol 

R  the  symbol  is  relocatable 

G  the  symbol  is  global 

The  final  value  of  the  symbol  is  expressed  in  octal.  If  the  symbol  is 
undefined  six  asterisks  are  printed  in  place  of  the  octal  number. 

CSECT  numbers  are  listed  if  the  symbol  is  in  a  named  CSECT.  All 
CSECTs  are  listed  at  the  end  of  the  table  with  their  lengths  and 
corresponding  number. 
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ABSEXPs 

******  Q 

ARGCNTa 

******  G 

ASSEM  s 

******  G 

BINCHNa 

000004 

bindat 

002322R 

004 

BLKTBLe 

002310R 

00a 

8PMB  s 

000020 

buftbl 

000374RG 

003 

CHAM 

002362R 

00a 

CHNSPC 

000312R 

003 

CHRPNTa 

******  G 

CLK50  a 

000040 

CMILENx 

000123 

CNTTBL 

000360RG 

003 

CONFIGa 

000300 

CONT 

000040RG 

010 

CORERR 

001726R 

010 

CPL  a 

000120 

CR  a 

000015 

CRFBUF 

002076RG 

004 

CRFC  a 

000040 

CRFCHNa 

000012 

CRFCNT 

000004RG 

007 

CRFDAT 

002352R 

00a 
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CRFFLG 

000000R 

007 
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003 
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003 

CRFTST 

000002RG 

007 
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000214R 

003 
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000000R 

003 

DATE 

001000R 

010 

DATTIM 

001004RG 

00a 

DEFEXT 

000104R 

003 

DEVFUL 

000252R 

003 

DIV60 

001240R 

010 

ONC  s 

******  G 

EDMASKa 

******  G 

ED.ABSa 

******  G 

EMTERRb 

000052 

ENDP1  a 

******  G 

ENDP2  » 

******  G 

ENDSWT 

000434R 

010 

ERR 

001662R 

010 

ERRB 

000102R 

010 

ERRBTSa 

******  G 

ERRCNT  * 

******  G 

EXMFLGa 

******  Q 

FF  s 

00001 4 

filnf 

000264R 

003 

FIN 

001434RG 

010 

FINCL 

001636R 

010 

FINMSG 

001030R 

004 

FINMS1 

001052R 

00a 

FINMS2 

001070R 

004 

FINP1 

000776R 

010 

FINP2 

080776R 

010 

FINSMl 

002124RG 

010 

FRECOR 

000006R 

007 

GETPLI 

001756RG 

010 

GETR503 

******  G 

GS A RG  a 

******  G 

HDRTTL 

001102RG 

00a 

HIGHADa 

000050 

ILLCMD 

000226R 

003 

ILLDEV 

000240R 

003 

IMPURT 

000042R 

007 

IMPURS 

000000R 

007 

INIOF 

000106R 

010 
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TIME 

00021 0R 

003 

TMPCNTa 

000014 

TTLBUFs 

******  G 

USRLOCs 

000046 

WRTERR 

002306R 

010 

XMIT0  s 

******  G 

SFLUSH 

002732RG 

010 

SREADW 

002422RG 

010 

SWRITW 

002134RG 

010 

.  abs. 

000000 

000 

000000 

001 

DPURE 

000000 

002 

DPURES 

000410 

003 

MIXED* 

002376 

004 

SWTSE* 

000000 

005 

SWTSEC 

000000 

006 

IMPUR* 

000042 

007 

MAINS 

003024 

010 

ERRORS  DETECTED: 

0 

FREE  CORE:  13431. 

WORDS 

TIMTIM 

001016R 

004 

TSTSTK 

001704RG 

010 

TTLLENb 

000040 

VT  a 

000013 

XBAW  s 

000000 

SCLOUT 

003006RG 

010 

SNLlSTa 

******  G 

SWAIT 

002730RG 

010 

TIMWRD  000204R  003 

TTLBRKs  ******  G 

TTYBUFs  000616 

WINST  =  104240 

XEOPICs  000000 

$EOABL=  ******  G 

SREAD  002422RG  010 

SWRITE  002134RG  010 


»  LP  1 /C/L 1  BEXaRPiii  RTP  AR»RPAR  AM,  RCIOCH,  RTEXEC 


Figure  5-4 
Symbol  Table 
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5. 5. 1.2  Page  Headings  -  The  MACRO  Assembler  outputs  each  page  in  the 
format  shown  in  Figure  5-3.  On  the  first  line  of  each  listing  page  the 
assembler  prints  (from  right  to  left) : 

1.  title  taken  from  .TITLE  directive  (most  recent  one 

encountered) 

2.  assembler  version  identification 

3.  the  date  and  time  of  day  if  entered 

4.  page  number 

The  second  line  of  each  listing  page  contains  the  subtitle  text 
specified  in  the  last  encountered  .SBTTL  directive. 


5. 5. 1.3  .TITLE  -  The  .TITLE  directive  is  used  to  print  a  heading  in 
the  output  listing  and  to  assign  a  name  to  the  object  module.  The 
heading  printed  on  the  first  line  of  each  page  of  the  listing  is  taken 
from  the  first  31  characters  of  the  argument  in  the  .TITLE  directive. 
The  first  six  characters  (symbol  name)  of  this  same  line  are  also  used 
as  the  name  of  the  object  module.  These  six  characters  must  be 
Radix-50  characters  (any  characters  beyond  the  first  six  are  ignored) . 
Won  Radix-50  characters  are  not  acceptable. 

For  example: 

.TITLE  P»0G  TO  PERFORM  DAILY  ACCOUNTING 

causes  PROG  TO  PERFORM  DAILY  ACCOUNTIN  to  be  printed  in  the  heading 
for  each  page  and  causes  the  object  module  of  the  assembled  program  to 
be  PROG  (this  name  is  distinguished  from  the  filename  of  the  object 
module  specified  in  the  command  string  to  the  assembler) . 

If  there  is  no  TITLE  statement,  the  default  name  assigned  to  the  first 
object  module  is: 

.MAIN, 

The  first  tab  or  space  following  the  .TITLE  directive  is  not 
considered  part  of  the  object  module  name  or  header  text,  although 
subsequent  tabs  and  spaces  are  significant. 

If  there  is  more  than  one  .TITLE  directive,  the  last  .TITLE  directive 
in  the  program  conveys  the  name  of  the  object  module. 


5. 5. 1.4  .SBTTL  -  The  .SBTTL  directive  is  used  to  provide  the 
elements  for  a  printed  table  of  contents  of  the  assembly  listing.  The 
text  following  the  directive  is  printed  as  the  second  line  of  each  of 
the  following  assembly  listing  pages  until  the  next  occurrence  of  a 
.SBTTL  directive. 

For  example : 

.SBTTL  CONDITIONAL  ASSEMBLIES 
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The  text: 


CONDITIONAL  ASSEMBLIES 

is  printed  as  the  second  line  of  each  of  the  following  assembly 
listing  pages. 

During  pass  1  of  the  assembly  process,  MACRO  automatically  prints  a 
table  of  contents  for  the  listing  containing  the  line  sequence  number 
and  text  of  each  . SBTTL  directive  in  the  program.  Such  a  table  of 
contents  is  inhibited  by  specifying  the  .NLIST  TOC  directive  within 
the  source . 

An  example  of  a  table  of  contents  is  shown  in  Figure  5-5. 


.MAIN,  RT-11  MACRO  VM02-09  5-SEP-74  22*30123 

table  OF  CONTENTS 


1-  29 

1-  37 

2-  1 

3-  1 

a-  i 
5-  1 

7-  1 

10*  l 
11-  2 
12-  2 

13-  1 

14-  1 

15-  1 

16-  1 

17-  1 

18-  1 

19-  1 

20-  1 
21-  1 
22-  1 

23-  1 

24-  1 

25-  1 

26-  l 

27-  1 

29-  1 


RT-U  MACRO  PARAMETER  FILE 
COMMON  PARAMETER  file 

ASSEMBLY  OPTIONS 
VARIABLE  parameters 
globals 

SECTOR  INITIALIZATION 
SUBROUTINE  CALL  DEFINITIONS 
MISCELLANEOUS  MACRO  DEFINITIONS 
MCIOCH  -  I/O  CHANNEL  ASSIGNMENTS 
****EXEC**** 

PROGRAM  START 
INIT  OUTPUT  FILES 
SWITCH  HANDLERS 
END-OF-PASS  ROUTINES 
SWITCH  AND  DATE  DATA  AREAS 
INIT  OUTPUT  FILES  (CONTINUED) 

FINISH  ASSEMBLY  AND  RESTART 

MEMORY  MANAGEMENT 

GET  PHYSICAL  SOURCE  LINE 

SYSTEM  MACRO  HANDLERS 

WRITE  ROUTINES 

READ  ROUTINE 

COMMON  I/O  ROUTINES 

MESSAGES 

I/O  TABLES 

FINIS 


Figure  5-5 

Assembly  Listing  Table  of  Contents 


Table  of  Contents  text  is  taken  from  the  text  of  each  .SBTTL 
directive.  The  associated  numbers  are  the  page  and  line  numbers  of 
the  .SBTTL  directives. 
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5. 5. 1.5  . 1 DENT  -  The  . IDENT  directive  is  not  used  or  supported  by 

the  RT-1.1  system,  but  is  handled  by  MACRO  for  compatability  with  other 
systems.  .IDENT  provides  a  means  of  labeling  the  object  module 
produced  as  a  result  of  a  MACRO  assembly.  In  addition  to  the  name 
assigned  to  the  object  modulo  with  the  .TITLE  directive,  a  character 
string  (up  to  six  characters,  treated  like  a  . RAD50  string)  can  be 
specified  between  paired  delimiters.  For  example t 

.IDENT  AO 05 A/ 

The  character  string* 

V005A 

is  converted  to  Radix-50  notation  and  output  to  the  global  symbol 
directory  of  the  object  module. 

When  more  than  one  .IDENT  directive  is  found  in  a  given  program,  the 
last  .IDENT  found  determines  the  symbol  which  is  passed  as  part  of  the 
object  module  identification. 


5. 5. 1.6  Page  Ejection  (.PAGE  Directive)  -  There  are  several  means  of 
obtaining  a  page  eject  in  a  MACRO  assembly  listing: 

1.  After  a  line  count  of  58  lines,  MACRO  automatically  performs 
a  page  eject  to  skip  over  page  perforations  on  line  printer 
paper  and  to  formulate  terminal  output  into  pages. 

2.  A  form  feed  character  used  as  a  line  terminator  (or  as  the 
only  character  on  a  line)  causes  a  page  eject.  Used  within  a 
macro  definition  a  form  feed  character  causes  a  page  eject. 
A  page  eject  is  not  performed  when  the  macro  is  invoked. 

3.  More  commonly,  the  .PAGE  directive  is  used  within  the  source 
code  to  perform  a  page  eject  at  that  point.  The  format  of 
this  directive  is* 

.PAGE 

This  directive  takes  no  arguments  and  causes  a  skip  to  the 
top  of  the  next  page. 

Used  within  a  macro  definition,  the  .PAGE  is  ignored,  but  the 
page  eject  is  performed  at  each  invocation  of  that  macro. 


5.5.2  Functions*  .ENABL  and  .DSABL  Directives 

Several  functions  are  provided  by  MACRO  through  the  .ENABL  and  .DSABL 
directives.  These  directives  use  3-character  symbolic  arguments  to 
designate  the  desired  function  and  are  of  the  forms* 

.ENABL  arg 
.DSABL  arg 

where  arg  is  one  of  the  legal  symbolic  arguments  defined  below. 
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The  following  list  describes  the  symbolic 
associated  functions  in  the  MACRO  languages 


arguments  and  their 


Symbolic 

Argument 


Function 


ABS  Enabling  of  this  function  (has  no  effect  in 

ASEMBL)  produces  absolute  binary  output; 
(i.e.,  for  input  to  the  Paper  Tape  Software 
System  absolute  binary  loader  using  a  .BIN 
extension  instead  of  .OBJ) .  The  default  case 
is  .DSABL  ABS. 

AMA  Enabling  of  this  function  directs  the 

assembly  of  all  relative  addresses  (address 
mode  67)  as  absolute  addresses  (address  mode 
37) .  This  switch  is  useful  during  the 
debugging  phase  of  program  development. 

CDR  The  statement  . ENABL  CDR  (has  no  effect  in 

ASEMBL)  causes  source  columns  73  and  greater 
to  be  treated  as  comments.  This  accommodates 
sequence  numbers  in  card  columns  72-80. 

FPT  Enabling  of  this  function  (has  no  effect  in 

ASEMBL)  causes  floating  point  truncation, 
rather  than  rounding  as  is  otherwise 
performed.  .DSABL  FPT  returns  to  floating 
point  rounding  mode. 

LC  Enabling  of  this  function  causes  the 

assembler  to  accept  lower  case  ASCII  input 
instead  of  converting  it  to  upper  case  (has 
no  effect  in  ASEMBL) . 

LSB  Enable  or  disable  a  local  symbol  block  (has 

no  effect  in  ASEMBL) .  While  a  local  symbol 
block  is  normally  entered  by  encountering  a 
new  symbolic  label  or  .CSECT  directive, 

. ENABL  LSB  forces  a  local  symbol  block  which 
is  not  terminated  until  a  label  of  .CSECT 
directive  following  the  .DSABL  LSB  statement 
is  encountered.  The  default  case  is  .DSABL 
LSB. 

PNC  The  statement  .DSABL  PNC  (has  no  effect  in 

ASEMBL)  inhibits  binary  output  until  an 
.ENABL  PNC  is  encountered.  The  default  case 
is  .ENABL  PNC. 

An  incorrect  argument  causes  the  directive  containing  it  to  be  flagged 
as  an  error. 


5.5.3  Data  Storage  Directives 

A  wide  range  of  data  and  data  types  can  be  generated  with  the 
following  directives  and  assembly  characters : 
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.BYTE 

.WORD 


.ASCII 
. ASCIZ 
. RAD50 
tB 
tD 
to 

These  facilities  are  explained  in  the  following  sections. 


5. 5. 3.1  .BYTE  -  The  .BYTE  directive  is  used  to  generate  successive 
bytes  of  data.  The  directive  is  of  the  forms 


.BYTE  exp  | WHICH  STORES  THE  OCTAL 

IEOUIVALENT  OF  THE  EXPRESSION 
>EXP  IN  THE  NEXT  BYTE 

.BITE  expl , exp 2 , JWHICH  STORES  THE  OCTAL 

iequivalents  OE  THE  list  qf 

> EXPRESSIONS  IN  SUCCESSIVE  BYTES, 


A  legal  expression  must  have  an  absolute  value  (or  contain  a  reference 
to  an  external  symbol)  and  must  result  in  eight  bits  or  less  of  data. 
The  16-bit  value  of  the  expression  must  have  a  high-order  byte  (which 
is  truncated)  that  is  either  all  zeros  or  all  ones.  Each  operand 
expression  is  stored  in  a  byte  of  the  object  program.  Multiple 
operands  are  separated  by  commas  and  stored  in  successive  bytes.  For 
example : 

3AM«5 

,■,♦410 

.BYTE  *D<*8 » SAM  1060  (OCTAL  EQUIVALENT  OF  48 

IDECIHAL)  IS  STORED  IN  location 
>411  *  005  IS  STORED  IN 
IL0CATI0N  411 

If  the  high-order  byte  of  the  expression  equates  to  a  value  other  them 
0  or  -1,  it  is  truncated  to  the  low-order  eight  bits  and  flagged  with 
a  T  error  code.  If  the  expression  is  relocatable,  an  A-type  warning 
flag  is  given. 

At  link  time  it  is  likely  that  relocation  will  result  in  an  expression 
of  more  them  eight  bits,  in  which  case,  the  Linker  prints  an  error 
message.  For  example: 
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B I 


.BYTE  83 
.BYTE  B 


/  STORES  OCTAL  83  IN  NEXT  BYTE 

/RELOCATABLE  VALUE  CAUSES  AN  "A« 
ierror  FLAG 


.6L0BL  X 
X  "3 

.BYTE  X  /  STORES  3  IN  NEXT  BYTE 

In  the  case  where  X  is  defined  in  another  program: 

.GLOBL  X 
.BYTE  X 

If  an  operand  following  the  .BYTE  directive  is  null,  it  is  interpreted 
as  a  zero.  For  example: 

.■•♦480 

.BYTE  ,,  /ZEROS  ARE  STORED  IN  BYTES 

1480,  481,  AND  488. 


5. 5. 3. 2  .WORD  -  The  .WORD  directive  is  used  to  generate  successive 
words  of  data.  The  directive  is  of  the  form: 

.WORD  exP  /WHICH  STORES  THE  OCTAL 

/EQUIVALENT  OF  THE  EXPRE3S0N 
I  EXP  IN  THE  NEXT  WORD 

.WORD  expl,exp2, . . .  /WHICH  STORES  THE  OCTAL 

/EQUIVALENTS  OF  THE  LIST  OF 
IEXPRESSIONS  IN  SUCCESSIVE 
/WORDS 

where  a  legal  expression  must  result  in  16  bits  or  less  of  data.  Each 
operand  expression  is  stored  in  a  word  of  the  object  program. 

Multiple  operands  are  separated  by  commas  and  stored  in  successive 
words.  For  example: 

SAL*0 
• • . *500 

.WORD  177535, ,*4, SAL  /STORES  177535,  506,  AND  0 

/IN  WORDS  5e0,  508,  AND  504. 

If  an  expression  equates  to  a  value  of  more  than  16  bits,  it  is 
truncated  and  flagged  with  a  T  error  code. 

If  an  operand  following  the  .WORD  directive  is  null,  it  is  interpreted 
as  zero.  For  example: 

,■•♦500 

.WORD  ,5,  /STORES  0,5,0  IN  LOCATIONS 

/ 500 ,  508,  AND  504 

A  blank  operator  field  (any  operator  not  recognized  as  a  macro  call, 
op-code,  directive  or  semicolon)  is  interpreted  as  an  implicit  .WORD 
directive.  Use  of  this  convention  is  discouraged.  The  first  term  of 
the  first  expression  in  the  operand  field  must  not  be  an  instruction 
mnemonic  or  assembler  directive  unless  preceded  by  a  +  or  -  operator. 
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For  example: 

,■,♦440  ( THE  OP-CODE  FOR  MOV,  WHICH  13 

LABEL!  ♦MOV, LABEL  >010000,  IS  STORED  IN  LOCATION 

>440,  440  IS  STOREO  IN 
(LOCATION  442. 

Note  that  the  default  .WORD  directive  occurs  whenever  there  is  a 
leading  arithmetic  or  logical  operator,  or  whenever  a  leading  symbol 
is  encountered  which  is  not  recognized  as  a  macro  call,  an  instruction 
mnemonic  or  assembler  directive.  Therefore,  if  an  instruction 
mnemonic,  macro  call,  or  assembler  directive  is  misspelled,  the  .WORD 
directive  is  assumed  and  errors  will  result.  Assume  that  MOV  is 
spelled  incorrectly  as  MOR: 

mor  a,b 

Two  error  codes  result:  A  and  U,  Two  words  are  then  generated,  one 
for  MOR  A  and  one  for  B. 


5.5. 3. 3  ASCII  Conversion  of  One  or  Two  Characters  -  The  '  and  " 
characters  are  used  to  generate  text  characters  within  the  source 
text.  A  single  apostrophe  followed  by  a  character  results  in  a  term 
in  which  the  7-bit  ASCII  representation  of  the  character  is  placed  in 
the  low-order  byte  and  zero  is  placed  in  the  high-order  byte.  For 
example : 


MOV  # ' A, R0 


results  in  the  following  16  bits  being  moved  into  RO : 
0000000001000001 


The  '  character  is  never  followed  by  a  carriage  return,  null,  RUBOUT, 
line  feed,  or  form  feed.  (For  another  use  of  the  '  character,  see 
Section  5. 6. 3. 6.) 


3TMNT I 


GETS VM 

BEQ 

4  S 

CMPB 

PCHRPNT, #•! 

BEQ 

LABEL 

CMPB 

PCHRPNT, #»• 

BEQ 

A8GMT 

(COLON  DELIMITS  LABEL  FIELD 

(EQUAL  DELIMITS 
(ASSIGNMENT  PARAMETER 


A  double  quote  followed  by  two  characters  results  in  a  term  in  which 
the  7-bit  ASCII  representations  of  the  two  characters  are  placed.  For 
example : 


MOV  «»AB,R0 

results  in  the  following  binary  word  being  moved  into  R0 : 
0100001001000001 

Note  that  the  first  character  is  placed  in  the  low-order  byte  and  the 
second  character  in  the  high-order  byte. 


5-40 


MACRO  Assembler 


The  "  character  Is  never  followed  by  a  carriage  return,  null,  rubout. 


or  form 

feed. 

For  example: 

I0EVICE 

NAME  TABLE 

• 

DEVNAMI 

.WORD 

»RF 

IRP  DISK 

.WORD 

"RK 

IRK  DISK 

DEVNKBI 

.WORD 

«TT 

| TERMINAL  KEYBOARD 

.WORD 

"DT 

IDECTAPE 

.WORO 

"LP 

1  LINE  PRINTER 

.WORD 

"PR 

IPAPER  TAPE  READER 

.WORD 

«PP 

IPAPER  TAPE  PUNCH 

.WORD 

0 

1  TABLE  *8  END 

5. 5. 3. 4  .ASCII  -  The  .ASCII  directive  translates  character  strings 
into  their  7-bit  ASCII  equivalents  for  use  in  the  source  program.  The 
format  of  the  .ASCII  directive  is: 

.ASCII  /character  string/ 

where:  character  string  is  a  string  of  any  acceptable  printing 

ASCII  characters  including  spaces.  The 
string  may  not  include  null  characters, 
rubout,  return,  line  feed,  vertical  tab, 
or  form  feed.  Nonprinting  characters 
can  be  expressed  in  digits  of  the 
current  radix  and  delimited  by  angle 
brackets.  (Any  legal,  defined 

expression  is  allowed  between  angle 
brackets . ) 

/  /  are  delimiting  characters  and  may  be  any 

printing  characters  other  than  ;  <  and  = 
characters  and  any  character  within  the 
string. 

As  an  example: 

A I  .ASCII  /HELLO/  IST0RE3  ASCII  REPRESENTATION  OP 

ITHE  LETTERS  H  E  L  L  0  IN 
^CONSECUTIVE  BYTES 

The  order  of  the  characters  as  they  are  stored  in  memory  is 
illustrated  below. 


5-41 


MACRO  Assembler 


1000 

1002 

1004 

1006 


.ASCII  /ABC7«15»«i2>/DEF/ 

I  STORES 

nei,  102,103,15, 12.1  e«,  IBS,  10b 

UN  CONSECUTIVE  BYTES 


.ASCII  /«AB*/  f  STORES  74,101,102,76  IN 
^CONSECUTIVE  BYTES 

The  ;  and  =  characters  are  not  illegal  delimiting  characters,  but  are 
preempted  by  their  significance  as  a  comment  indicator  and  assignment 
operator,  respectively.  For  other  than  the  first  group,  semicolons 
are  treated  as  beginning  a  comment  field.  For  example: 


Directive 

Result 

Explanation 

•ASCII 

;ABC;/DEF/ 

A  B 

C  D  E  F 

Acceptable ,  but  not 

recommended  procedure. 

•ASCII 

/ABC/;DEF; 

A  B 

C 

;DEF;  is  treated  as  a  comment 
and  ignored. 

•ASCII 

/ABC/=DEF= 

A  B 

C  D  E  F 

Acceptable ,  but  not 

recommended  procedure. 

•ASCII 

«def» 

The  assignment  ,ASCII=DEF  is 

performed  and  an  error 
generated  upon  encountering 
the  second  =. 


5. 5. 3. 5  . ASCIZ  -  The  .ASCIZ  directive  is  equivalent  to  the  .ASCII 
directive  with  a  zero  byte  automatically  inserted  as  the  final 
character  of  the  string.  For  example: 

When  a  list  or  text  string  has  been  created  with  a 
.ASCIZ  directive,  a  search  for  the  null  character 
can  determine  the  end  of  the  list  as  follows: 

CR«  15 
LF»  12 


MOV  #HEU0,«1 
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XI 


MOV 

mqvb 


BNE  X 


PLINBUF  , R2 
(*»!)♦» (R2)* 


HELLO  I  •  ASCIZ 


IMOVE  A  character  OF  THE 
JMESSAGE  STRING  INTO  THE 
IOUTPUT  BUFFER 
IBRANCH  BACK  IF  BVTE 
INOT  EQUAL  TO  0 


<CR>«LF>/MACRO*U  V001 A/<CR»<LF» 
IINTRO  MESSAGE 


5. 5. 3. 6  . RAD50  -  The  .RAD50  directive  allows  the  user  the  capability 
to  handle  symbols  in  Radix— 50  coded  form  (this  form  is  sometimes 
referred  to  as  MOD40  and  is  used  in  PDP-11  system  programs) .  Radix-50 
form  allows  three  characters  to  be  packed  into  sixteen  bits; 
therefore,  any  6-character  symbol  can  be  held  in  two  words.  The  form 
of  the  directive  is: 


where : 


. RAD50 
/  / 

string 


/string/ 


delimiters  can  be  any  printing 
characters  other  than  the  =  ,  <,  and  ; 
characters . 

is  a  list  of  the  characters  to  be 
converted  (three  characters  per  word) 
and  may  consist  of  the  characters  A 
through  Z,  0  through  9,  dollar  ($) ,  dot 
(.)  and  space  (  ) .  If  there  are  fewer 
than  three  characters  (or  if  the  last 
set  is  fewer  than  three  characters)  they 
are  considered  to  be  left  justified  and 
trailing  spaces  are  assumed.  Illegal 
nonprinting  characters  are  replaced  with 
a  ?  character  and  cause  an  I  error  flag 
to  be  set.  Illegal  printing  characters 
set  the  Q  error  flag. 

The  trailing  delimiter  may  be  a  carriage  return,  semicolon,  or 
matching  delimiter.  (A  warning  code  is  printed  if  it  is  not  a 
matching  delimiter,  however.)  For  example: 


21 


00050  014400 


003223 

• RAD50 

/ABC 

)  PACK 

ABC  INTO  ONE  WORD 

003220 

• RAO50 

/AB/ 

IPACK 

AB  (SPACE)  INTO  ONE 

WORD. 

000000 

.RAD50 

// 

IPACK 

THREE  SPACES  INTO  ONE  W0R0 

003223 

.RAD50 

/ ABCD/ 

1  PACK 

ABC  INTO  FIRST  NORD 

AND 

»D  (SPACE) (SPACE)  INTO  SECOND  WORD 


Each  character  is  translated  into  its  Radix— 50  equivalent  as 
indicated : 
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Radix- 50 

Character  Equivalent  (octal)  ASCII  (octal) 


(space) 

A-Z 

$ 


0 

1-32 


40 


101-132 


33 

34 

35 


44 

56 


undefined 

0-9 


36-47 


undefined 

60-71 


Note  that  (mother  character  could  be  defined  for  code  35 ,  which  is 
currently  unused. 

The  Radix-50  equivalents  for  three  characters  (C1,C2,C3)  are  combined 
in  one  16-bit  word  as  follows: 


Radix-50  value  -  ( (Cl*50) +C2) *50+C3 


For  example: 

Radix-50  value  of  ABC  is  ( (1*50) +2) *50+3  or  3223 

See  Appendix  E  for  a  table  to  quickly  determine  Radix-50  equivalents. 

Use  of  angle  brackets  is  encouraged  in  the  .ASCII ,  .ASCIZ,  and  . RAD50 
statements  whenever  leaving  the  text  string  to  insert  special  codes. 
For  example: 


.ASCII  «101>  ^EQUIVALENT  TO  .ASCII/A/ 

, RAD50  / AB/«35> I  STORES  3255  IN  NEXT  H0RD. 

CHR1M 

CHR2*2 

CHR3«3 


RAD50  <CHR1*«CHR2><CHR3» 


^EQUIVALENT  TO  RAQ50/ABC/ 


5.5.4  Radix  Control 

5. 5. 4.1  .RADIX 

Numbers  used  in  a  MACRO  source  program  are  initially  considered  to  be 
octal  numbers.  However,  the  programmer  has  the  option  of  declaring 
the  following  radices: 

2,  4,  8,  10 

This  is  done  via  the  .RADIX  directive  of  the  form: 


.RADIX  n 

where  n  is  one  of  the  acceptable  radices 
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The  argument  to  the  .RADIX  directive  is  always  interpreted  in  decimal 
radix.  Following  any  radix  directive,  that  radix  is  the  assumed  base 
for  any  number  specified  until  the  following  .RADIX  directive. 

The  default  radix  at  the  start  of  each  program,  and  the  argument 
assumed  if  none  is  specified,  is  8  (octal).  For  example: 

.RADIX  10  I  BEGINS  SECTION  OF  CODE  WITH 

IDECIMAL  RADIX 


tfU01x  J  reverts  to  octal  raoix 

In  general  it  is  recommended  that  macro  definitions  not  contain  or 
rely  on  radix  settings  from  the  .RADIX  directive.  The  temporary  radix 
control  characters  should  be  used  within  a  macro  definition.  (tD,  to, 
and  tB  are  described  in  the  following  section.)  A  given  radix  is  valid 
throughout  a  program  until  changed.  Where  a  possible  conflict  exists 
within  a  macro  definition  or  in  possible  future  uses  of  that  code 
module,  it  is  suggested  that  the  user  specify  values  using  the 
temporary  radix  controls. 


5. 5. 4. 2  Temporary  Radix  Control:  tD,  to,  and  tB  -  Once  the  user  has 
specified  a  radix  for  a  section  of  code,  or  has  determined  to  use  the 
default  octal  radix,  he  may  discover  a  number  of  cases  where  an 
alternate  radix  is  more  convenient  (particularly  within  macro 
definitions).  For  example,  the  creation  of  a  mask  word  might  best  be 
done  in  the  binary  radix. 

MACRO  has  three  unary  operators  to  provide  a  single  interpretation  in 
a  given  radix  within  another  radix  as  follows: 

tDx  (x  is  treated  as  being  in  decimal  radix) 

tOx  (x  is  treated  as  being  in  octal  radix) 

tBx  (x  is  treated  as  being  in  binary  radix) 

For  example: 

tD123 
tO  47 

tB  00001101 
tO<A+3> 

Notice  that  while  the  uparrow  and  radix  specification  characters  may 
not  be  separated,  the  radix  operator  can  be  physically  separated  from 
the  number  by  spaces  or  tabs  for  formatting  purposes.  Where  a  term  or 
expression  is  to  be  interpreted  in  another  radix,  it  should  be 
enclosed  in  angle  brackets. 

These  numeric  quantities  may  be  used  any  place  where  a  numeric  value 
is  legal. 

A  temporary  radix  change  from  octal  to  decimal  may  be  made  by 
specifying  a  decimal  radix  number  with  a  "decimal  point".  For  example: 
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100.  (144(8)) 

1376.  (2540(8)) 

128.  (200(8)) 


5.5.5  Location  Counter  Control 

The  four  directives  that  control  movement  of  the  location  counter  are 
.EVEN  and  .ODD  which  move  the  counter  a  maximum  of  one  byte,  and  .BLKB 
and  .BLKW  which  allow  the  user  to  specify  blocks  of  a  given  number  of 
bytes  or  words  to  be  skipped  in  the  assembly. 


5. 5. 5.1  .EVEN  -  The  .EVEN  directive  ensures  that  the  assembly 
location  counter  contains  an  even  memory  address  by  adding  one  if  the 
current  address  is  odd.  If  the  assembly  location  counter  is  even,  no 
action  is  taken.  Any  operands  following  a  .EVEN  directive  are 
ignored. 


The  .EVEN  directive  is  used  as  follows: 


.ASCII  /THIS  IS  A  TEST/ 
•  EVEN 

.WORD  XYZ 


(  ASSURES  NEXT  STATEMENT 
I  BEGINS  ON  A  WORD  BOUNDARY 


5. 5. 5. 2  .ODD  -  The  .ODD  directive  ensures  that  the  assembly  location 
counter  is  odd  by  adding  one  if  it  is  even.  For  example: 


) CODE  TO  MOVE  DATA  FROM  AN  INPUT  LINE 
|T0  A  BUFFER 


N»5 


(BUFFER  HAS  5  WORDS 


BUFFI 


ODD 

BYTE  N*2 

blkw  n 


»C0UNT«2N  BYTES 

(RESERVE  SUFFER  OF  N  WORDS 


AGAIN! 


DONE  I 


LINEI 


MOV  iBUFF t R2 
MOV  RLINE'Rl 
M0 VB  -l(R2),R0 
M0VB  (Rl) ♦» (R2) ♦ 
BEQ  DONE 
DEC  R0 
BNE  AGAIN 


( ADDRESS  OF  EMPTY  BUFFER  IN  R2 
(ADDRESS  OF  INPUT  LINE  IS  IN  Rl 
(GET  COUNT  STORED  IN  BUFF-i  IN  R0 

(MOVE  BYTE  FROM  LINE  INTO  BUFFER 
(WAS  NULL  CHARACTER  SEEN? 

(DECREMENT  COUNT 
( NOT*0,  GET  NEXT  CHARACTER 


* 


CLRB  * (R2) 


(OUT  OF  ROOM  IN  BUFFER,  CLEAR  LAST 
(WORD 


.ASCII  /TEXT/ 
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In  this  case,  .ODD  is  used  to  place  the  buffer  byte  count  in  the 
preceding  the  buffer,  as  follows: 


byte 


5. 5. 5. 3  .BLKB  and  .BLKW  -  Blocks  of  storage  can  be  reserved  using 
the  .BLKB  and  .BLKW  directives.  .BLKB  is  used  to  reserve  byte  blocks 
and  .BLKW  reserves  word  blocks.  The  two  directives  are  of  the  form: 

.BLKB  exp 
.BLKW  exp 

where  exp  is  the  number  of  bytes  or  words  to  reserve.  If  no  argument 
xs  present,  1  is  the  assumed  default  value.  Any  legal  expression 
which  is  completely  defined  at  assembly  time  and  produces  an  absolute 
number  is  legal.  For  example: 


1 

2 

3 


4 

000000 *  .CSECT  IMPURE 

5  000000 

b 

PASS  1  .BLKW 

7  000002 

SYMBOL  1  .BLKW 

2 

8  000006 

MODE  1 

9  000006 

FLAGS:  .BLKB 

1 

10  00007 

SECTOR!  .BLKB 

1 

11  00010 

VALUE:  .BLKW 

1 

12  00012 

RELLVL*  .BLKW 

i 

13 

.BLKW 

2 

14  00020 

CLCNAM:  .BLKW 

2 

IS  00024 

CLCFGS!  .BLKB 

1 

16  0002S 

CLCSEC!  .BLKB 

1 

17  00026 

CLCLOC!  .BLKW 

i 

18  00030 

CLCMAX!  .BLKW 

l 

19 

000001*  .END 

I  next  GROUP  MUST  stay  together 
f  SYMBOL  ACCUMULATOR 

If  LAG  BITS 

I  SYMBOL/EXPRESSION  TYPE 
^expression  value 

/END  OF  GROUPED  DATA 
ICURRENJ  LOCATION  COUNTER 


The  .BLKB  directive  has  the  same  effect  as: 


.=.+exp 

but  is  easier  to  interpret  in  the  context  of  source  code. 


5.5.6  Numeric  Control 

Several  directives  are  available  to  provide  software  complements  to 
the  floating-point  hardware  on  the  PDP-11. 
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A  floating-point  number  is  represented  by  a  string  of  decimal  digits. 
The  string  (which  can  be  a  single  digit  in  length)  may  optionally 
contain  a  decimal  point,  and  may  be  followed  by  an  optional  exponent 
indicator;  in  the  form  of  the  letter  E  and  a  signed  decimal  exponent. 
The  list  of  number  representations  below  contains  seven  distinct, 
valid  representations  of  the  same  floating-point  number; 


3 

3. 

3.0 
3.0E0 
3E0 
•  3E1 
300E-2 

As  can  be  quickly  inferred,  the  list  could  be  extended  indefinitely 
(e.g.,  3000E-3,  .03E2,  etc.).  A  leading  plus  sign  is  ignored  (e.g., 

+3.0  is  considered  to  be  3.0).  Leading  minus  signs  complement  the  sign 
bit.  No  other  operators  are  allowed  (e.g.,  3.0+N  is  illegal). 

Floating-point  number  representations  are  valid  only  in  the  contexts 
described  in  the  remainder  of  this  section. 

Floating-point  numbers  are  normally  rounded.  That  is,  when  a 
floating-point  number  exceeds  the  limits  of  the  field  in  which  it  is 
to  be  stored,  the  high-order  excess  bit  is  added  to  the  low-order 
retained  bit.  For  example,  if  the  number  were  to  be  stored  in  a 
2-word  field,  but  more  than  32  bits  were  needed  for  its  value,  the 
highest  bit  carried  out  of  the  field  would  be  added  to  the  least 
significant  position.  In  order  to  enable  floating-point  truncation, 
the  . ENABL  FPT  directive  is  used  and  .DSABL  FPT  is  used  to  return  to 
floating-point  rounding. 


5. 5. 6.1  .FLT2  and  .FLT4  -  Like  the  .WORD  directive,  the  two 
floating-point  storage  directives  cause  their  arguments  to  be  stored 
in-line  with  the  source  program  (have  no  effect  in  ASEMBL) .  These  two 
directives  are  of  the  form; 

.FLT2  argl,arg2 ,. . . 

.FLT4  argl,arg2,... 

where  argl,arg2,  etc.  represent  one  or  more  floating  point  numbers 
separated  by  commas. 

•FLT2  causes  two  words  of  storage  to  be  generated  for  each  argument 
while  .FLT4  generates  four  words  of  storage. 
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The  following  code  was  assembled  with  the  4-word  floating-point  math 
package  t 


1 

2 

3 

4  000006)  037314  ATOFTBI 
000002  146314 
000004  146314 
000006  14631b 

5  000010  036443 
000012  153412 
000014  036560 
000016  121727 

6  000020  034721 
000022  133427 
000024  054342 
000026  014545 

7  000030  031453 
000032  146167 
000034  010604 
000036  060717 

6  000040  022746 
000042  112624 
000044  137304 
000046  046741 

9  000050  005517 
000052  130436 
000054  126505 
000056  034625 


.FLTA  1,6-1  »10*-i 

,FLT4  1,6-2  110**2 

FLT4  1,6-4  f  1 0*i>4 

FLT4  1,6-8  I10--8 

FLT«  1,6-16  M0*-16 

FLT4  1,6-32  M0--32 


5. 5. 6, 2  Temporary  Numeric  Control*  tF  and  tC  -  Like  the  temporary 
radix  control  operators,  operators  are  available  to  specify  either  a 
1-word  floating-point  number  (tF — not  available  in  ASEMBL)  or  the 
one's  complement  of  a  1-word  number  (tC),  For  example* 


FL3.7*  tF3»7 


creates  a  1-word  floating-point  number  at  location  FL3.7  containing 
the  value  3.7  as  follows  * 


SIGN 

BIT 


15  14 


EXPONENT 


MANTISSA 


This  1-word  floating-point  number  is  the  first  word  of  the  2-  or 
4-word  floating-point  number  format  shown  in  the  PDP-11  PROCESSOR 
HANDBOOK,  and  the  statement* 

CMP 151  *  tC151 

stores  the  one's  complement  of  151  in  the  current  radix  (assume 
current  radix  is  octal)  as  follows* 
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177626 


Since  these  control  operators  are  unary  operators,  their  arguments  may 
be  integer  constants  or  symbols,  and  the  operators  may  be  expressed 
successively.  For  example: 


tCtD25 


or 


tC31 


or  177746 


The  term  created  by  the  unary  operator  and  its  argument  is  then  a  term 
which  can  be  used  by  itself  or  in  an  expression.  For  example: 

tC2+6 


is  equivalent  to: 


<tC2>+6  or  177775+6  or  000003 


For  this  reason,  the  use  of  angle  brackets  is  advised.  Expressions 
used  as  terms  or  arguments  of  a  unary  operator  must  be  explicitly 
grouped. 


An  example  of  the  importance 
operators  is  shown  below: 


of 


ordering  with  respect  to 


unary 


tFl.O  «  040200 

tF— 1.0  =  140200 

-tFl.O  =  137600 

— tF— 1.0  =  037600 


The  argument  to  the  tF  operator  must  not  be  an  expression  and  should 
be  of  the  same  format  as  arguments  to  the  .FLT2  and  .FLT4  directives. 


5.5.7  Terminating  Directives 


5. 5. 7.1  .END  -  The  .END  directive  indicates  the  physical  end  of  the 
source  program.  The  .END  directive  is  of  the  form: 


.END  exp 


where  exp  is  an  optional  argument  which,  if  present,  indicates 
program  entry  point,  i.e.,  the  transfer  address. 


the 
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When  the  load  module  is  loaded,  program  execution  begins  at  the 
transfer  address  indicated  by  the  .END  directive.  In  a  runtime  system 
(the  load  module  output  of  the  Linker)  a  .END  exp  statement  should 
terminate  the  first  object  module  and  .END  statements  should  terminate 
any  other  object  modules. 


5.5. 7.2  .EOT  -  Under  the  RT-11  System,  the  .EOT  directive  is 
ignored.  The  physical  end  file  allows  several  physically  separate 
tapes  to  be  assembled  as  one  program. 


5.5.8 


Program  Boundaries  Directives 


.LIMIT 


The  .LIMIT  directive  reserves  two  words  into  which  the  Linker  puts  the 
low  and  high  addresses  of  the  load  module's  relocatable  code  (the  load 
module  is  the  result  of  the  link) .  The  low  address  (inserted  into  the 
first  word)  is  the  address  of  the  first  byte  of  code.  The  high 
address  is  the  address  of  the  first  free  byte  following  the  relocated 
code.  These  addresses  are  always  even  since  all  relocatable  sections 
are  loaded  at  even  addresses.  (If  a  relocatable  section  consists  of 
an  odd  number  of  bytes,  the  Linker  adds  one  to  the  size  to  make  it 
even.) 


5.5.9  Program  Section  Directives 

The  assembler  provides  for  255(10)  program  sections:  an  absolute 
section  declared  by  .ASECT,  an  unnamed  relocatable  program  section 
declared  by  .CSECT,  and  253(10)  named  relocatable  program  sections 
declared  by  .CSECT  symbol,  where  symbol  is  any  legal  symbolic  name. 
These  directives  allow  the  user  to: 

1.  Create  his  program  (object  module)  in  sections: 

The  assembler  maintains  separate  location  counters  for  each 
section.  This  allows  the  user  to  write  statements  which  are 
not  physically  contiguous  but  will  be  loaded  contiguously. 
The  following  examples  will  clarify  this: 
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A  I 
8 1 
Cl 
8TI 


.CSECT 

0 

0 

0 

CLH  A 
CLR  B 
CUR  C 
.ASECT 
« *4 

•  WORD  , *2, HALT 
•CSECT 

INC  A 
BR  ST 
.END 


ISTART  THE  UNNAMED  RELOCATABLE  SECTION 

I  ASSEMBLED  AT  RELOCATABLE  0, 

(RELOCATABLE  2  AND 

(RELOCATABLE  4 

(ASSEMBLE  CODE  AT 

(RELOCATABLE  AD0RE88 

(8  THROUGH  21 

ISTART  THE  ABSOLUTE  SECTION 
(ASSEMBLE  CODE  AT 
(ABSOLUTE  4  THROUGH  7 
(RESUME  THE  UNNAMED  RELOCATABLE 
(SECTION 

IASSEMBLE  CODE  AT 
(RELOCATABLE  22  THROUGH  27 


The  first  appearance  of  .CSECT  or  .ASECT  assumes  the  location 
counter  is  at  relocatable  or  absolute  zero,  respectively. 
The  scope  of  each  directive  extends  until  a  directive  to  the 
contrary  is  given.  Further  occurrences  of  the  same  .CSECT  or 
.ASECT  resume  assembling  where  the  section  was  left  off. 


.CSECT 

COM! 

I0ECLARE  SECTION  C0M1 

Al 

0 

(ASSEMBLED  AT  RELOCATABLE 

0 

Bl 

0 

IASSEHBLED  AT  RELOCATABLE 

2 

Cl 

0 

(ASSEMBLED  AT  RELOCATABLE 

4 

.CSECT 

COM2 

(DECLARE  SECTION  COM2 

XI 

0 

(ASSEMBLED  AT  RELOCATABLE 

0 

V 1 

0 

(ASSEMBLED  AT  RELOCATABLE 

2 

.CSECT 

C0M1 

(RETURN  TO  C0M1 

01 

0 

(ASSEMBLED  AT  RELOCATABLE 

8 

.END 

The  assembler  automatically  begins  assembling  at  relocatable 
zero  of  the  unnamed  .CSECT  if  not  instructed  otherwise;  that 
is,  the  first  statement  of  an  assembly  is  an  implied  .CSECT. 

All  labels  in  an  absolute  section  are  absolute;  all  labels 
in  a  relocatable  section  are  relocatable.  The  location 
counter  symbol,  is  relocatable  or  absolute  when 
referenced  in  a  relocatable  or  absolute  section, 
respectively.  Undefined  internal  symbols  are  assigned  the 
value  of  relocatable  or  absolute  zero  in  a  relocatable  or 
absolute  section,  respectively.  Any  labels  appearing  on  a 
.ASECT  or  .CSECT  statement  are  assigned  the  value  of  the 
location  counter  before  the  .ASECT  or  .CSECT  takes  effect. 
Thus,  if  the  first  statement  of  a  program  is: 

A I  .ASECT 

then  A  is  assigned  to  relocatable  zero  and  is  associated  with 
the  unnamed  relocatable  section  (because  the  assembler 
implicitly  begins  assembly  in  the  unnamed  relocatable 
section) . 

Since  it  is  not  known  at  assembly  time  where  the  program 
sections  are  to  be  loaded,  all  references  between  sections  in 
a  single  assembly  are  translated  by  the  assembler  to 
references  relative  to  the  base  of  that  section.  The 
assembler  provides  the  Linker  with  the  necessary  information 
to  resolve  the  linkage.  Note  that  this  is  not  necessary  when 
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making  a  reference  to  an  absolute  section  (the 
knows  all  load  addresses  of  an  absolute  section) . 

Examples : 


assembler 


A  I 


.asect 
. *1000 

CL*  X 
JMP  Y 


>  ASSEMBLED  AS  CLR  BASE  OF  UNNAMED 
RELOCATABLE  SECTION  *12 
) ASSEMBLED  AS  JMP  BASE  OF  UNNAMED 
RELOCATABLE  SECTION  ♦  10 


Y I 
XI 


.C3ECT 
MOV  R0,R1 
JMP  A 
HALT 
0 

.END 


lASSEMBLED  AS  JMP  1000 


In  the  above  example  the  references  to  X  and  Y  were 
translated  into  references  relative  to  the  base  of  the 
unnamed  relocatable  section. 

2.  Share  code  and/or  data  between  object  modules  (separate 
assemblies) t 

Named  relocatable  program  sections  operate  as  FORTRAN  labeled 
COMMON;  that  is,  sections  of  the  same  name  from  different 
assemblies  are  all  loaded  at  the  same  location  by  LINK.  The 
unnamed  relocatable  section  is  the  exception  to  this  as  all 
unnamed  relocatable  sections  are  loaded  in  unique  areas  by 
LINK. 

Note  that  there  is  no  conflict  between  internal  symbolic 
names  and  program  section  names;  that  is,  it  is  legal  to  use 
the  same  symbolic  name  for  both  purposes.  In  fact, 
considering  FORTRAN  again,  this  is  necessary  to  accommodate 
the  FORTRAN  statement: 


COMMON 


/X/A,B,C,X 


where  the  symbol  X  represents  the  base  of  this  program 
section  and  also  the  fourth  element  of  this  program  section. 

Program  section  names  should  not  duplicate  .GLOBL  names.  In 
FORTRAN  language,  COMMON  block  names  and  SUBROUTINE  names 
should  not  be  the  same. 


The  .ASECT  and  .CSECT  program  section  directives  are  provided  in  MACRO 
to  allow  the  user  to  specify  an  unnamed  absolute  or  relocatable 
section.  These  directives  are  formatted  as  follows t 

.ASECT 

.CSECT 

.CSECT  symbol 
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The  single  absolute  section  can  be  declared  with  an: 

.ASECT 

directive.  No  name  can  be  associated  with  the  absolute  section 
specified  by  means  of  the  .ASECT  directive.  The  single  unnamed 
relocatable  program  section  can  be  declared  with  a: 

. CSECT 

directive. 

All  named  relocatable  sections  are  loaded  in  unique  areas  by  LINK.  Up 
to  253(10)  named  relocatable  program  sections  cam  be  declared  with: 

.CSECT  symbol 

directives,  where  symbol  is  amy  legal  symbolic  name. 

The  assembler  automatically  begins  assembling  at  relocatable  zero  of 
the  unnamed  .CSECT  if  not  instructed  otherwise;  that  is,  the  first 
statement  of  an  assembly  is  an  implied  .CSECT. 


5.5.10  Symbol  Control:  .GLOBL 

If  a  program  is  created  in  segments  which  are  assembled  separately, 
global  symbols  are  used  to  allow  reference  to  one  symbol  by  the 
different  segments. 

A  global  symbol  must  be  declared  in  a  .GLOBL  directive.  The  form  of 
the  .GLOBL  directive  is: 

. GLOBL  syml , sym2 , . . . 


where : 

syml,sym2,  etc.  are  legal  symbolic  names,  separated  by 

commas,  tabs,  or  spaces  where  more  than 
one  symbol  is  specified. 

Symbols  appearing  in  a  .GLOBL  directive  are  either  defined  within  the 
current  program  or  are  external  symbols,  in  which  case  they  are 
defined  in  another  program  which  is  to  be  linked  with  the  current 
program,  by  LINK,  prior  to  execution. 

A  .GLOBL  directive  line  may  contain  a  label  in  the  label  field  and 
comments  in  the  comment  field. 

At  the  end  of  assembly  pass  1,  MACRO  has  determined  whether  a  given 
global  symbol  is  defined  within  the  program  or  is  expected  to  be  an 
external  symbol. 


5-54 


MACRO  Assembler 


fOE^lNC  A  SUBROUTINE  WITH  2  ENTRY  POINTS  WHICH 
KALIS  AN  EXTERNAL  SUBROUTINE 


•CSECT  IDECLARE  THe  CONTROL  SECTION 

•  GL08L  A,B»C  (DECLARE  A,B,C  AS  GL08ALS 

MOV  *(R5)*,R0  (ENTRY  A  IS  DEFINED 

MOV  #X ,  R 1 

FC*C  (CALL  EXTERNAL  SUBROUTINE  C 
»TS  R3  (EXIT 

MOV  B(R5)4,R1  IOEFINE  ENTRY  B 

CLR  R1 

BR  X 


In  the  previous  example,  A  and  B  are  entry  symbols  (entry  points),  C 
is  an  external  symbol  and  X  is  an  internal  symbol. 

A  global  symbol  is  defined  only  when  it  appears  in  a  . GLOBL  directive. 
A  symbol  is  not  considered  a  global  symbol  if  it  is  assigned  the  value 
of  a  global  expression  in  a  direct  assignment  statement. 


References  to  external  symbols  can  appear  in  the  operand  field  of  an 
instruction  or  assembler  directive  in  the  form  of  a  direct  reference, 
i.e.s  ' 


CLR  EXT 

.WORD  EXT 

CLR  #EXT 

or  a  direct  reference  plus  or  minus  a  constant,  i.e.: 

OwB 

CLR  EXT*D 

•  WORD  EXT- 2 

CLR  BEXT+0 

An  external  symbol  cannot  be  used  in  the  evaluation  of  a  direct 
assignment  expression.  A  global  symbol  defined  within  the  program  can 
be  used  in  the  evaluation  of  a  direct  assignment  statement. 


5.5.11  Conditional  Assembly  Directives 

Conditional  assembly  directives  provide  the  programmer  with  the 
capability  to  conditionally  include  or  ignore  blocks  of  source  code  in 
the  assembly  process.  This  technique  is  used  extensively  to  allow 
several  variations  of  a  program  to  be  generated  from  the  source 
program. 

The  general  form  of  a  conditional  block  is  as  follows* 

.IP  cond , argument ( s )  ; START  CONDITIONAL  BLOCK 

•  ; STATEMENTS  IN  RANGE  OF 

•  ; CONDITIONAL 

.  ; BLOCK 

•ENDC  7 END  CONDITIONAL  BLOCK 

where*  cond  is  a  condition  which  must  be  met  if  the  block  is 

to  be  included  in  the  assembly.  These  conditions 
are  defined  below. 
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argument (s)  are  a  function  of  the  condition  to  be  tested*  If 
more  than  one  argument  is  specified,  they  must  be 
separated  by  commas* 

range  is  the  body  of  code  which  is  included  in  the 

assembly  or  ignored  depending  upon  whether  the 
condition  is  met. 


The  following 

are  the 

allowable  conditions: 

Conditions 

Positive  Complement 

Arguments 

Assemble  Block  If 

EQ 

NE 

expression 

expressions  (or/0) 

GT 

LE 

expression 

expressions  (or£0) 

LT 

GE 

expression 

expressions  (or^O) 

DF 

NDF 

symbolic 

argument 

symbol  is  defined 
(or  undefined) 

B 

NB 

macro- type 
argument 

argument  is  blank 
(or  nonblank) 

IDN 

DIF 

two  macro-type 
arguments  separated 
by  a  comma 

arguments  identical 
(or  different) 

Z 

NZ 

expression 

same  as  EQ/NE 

G 

expression 

same  as  GT/LE 

L 

expression 

same  as  LT/GE 

IF  DIF  and  IF 

IDN  are 

not  available  in  ASEMBL. 

NOTE 

A  macro-type  argument  is  enclosed  in 
angle  brackets  or  within  an  up-arrow 
construction  (as  described  in  Section 
5. 2. 1.1).  For  example: 

<A,B,C> 

t/124/ 

For  example: 

ALPHAf-1 

.IF  EQ.ALPHAM  | ASSEMBLE  IF  ALPHA  +  IS 

,EN0C 

Within  the  conditions  DF  and  NDF  the  following  two  operators  are 
allowed  to  group  symbolic  arguments: 

&  logical  AND  operator 

I  logical  inclusive  OR  operator 
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For  example: 

.IF  DF,3YM1  *  8  YM2  I  ASSEMBLE  IF  BOTH  SYM1 
*  fANO  SYM2  ARE  DEFINED 

I 

.ENOC 


5.5.11.1  Subconditionals  -  Subconditionals  may  be  placed  within 
conditional  blocks  to  indicate: 

1.  assembly  of  an  alternate  body  of  code  when  the  condition  of 
the  block  indicates  that  the  code  within  the  block  is  not  to 
be  assembled, 

2.  assembly  of  a  non- contiguous  body  of  code  within  the 

conditional  block  depending  upon  the  result  of  the 

conditional  test  to  enter  the  block, 

3.  unconditional  assembly  of  a  body  of  code  within  a  conditional 
block. 

There  are  three  subconditional  directives,  as  follows: 

Subconditional  Function 

.IFF  The  code  following  this  statement  up  to  the  next 

subconditional  or  end  of  the  conditional  block  is 
included  in  the  program  if  the  value  of  the 

condition  tested  upon  entering  the  conditional 
block  is  false. 

.IFT  The  code  following  this  statement  up  to  the  next 

subconditional  or  end  of  the  conditional  block  is 
included  in  the  program  if  the  value  of  the 

condition  tested  upon  entering  the  conditional 
block  is  true. 

. IFTF  The  code  following  this  statement  up  to  the  next 

subconditional  or  the  end  of  the  conditional  block 
is  included  in  the  program  regardless  of  the  value 
of  the  condition  tested  upon  entering  the 
conditional  block. 

The  implied  argument  of  the  subconditionals  is  the  value  of  the 

condition  upon  entering  the  conditional  block.  Subconditionals  are 
used  within  outer  level  conditional  blocks.  Subconditionals  are 
ignored  within  nested,  unsatisfied  conditional  blocks. 


For  example: 
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.IF  OF, SYM  I  ASSEMBLE  BLOCK  IF  SYM  IS  DEFINED 

.IFF  | ASSEMBLE  THE  FOLLOWING  CODE  ONLY  IF 

f  SYM  IS  UNOEFINEO 


IFT  I  ASSEMBLE  THE  FOLLOWING  COOE  ONLY  IF 

I SYM  IS  DEFINED 

,iftf  ^assemble  the  following  code 

f UNCONDITIONALLY 


(ENOC 


.IF 

.IF 

.IFF 

• 

• 

OF  *  X 
OF,  Y 

i assembly  tests  false 

ITE8TS  FALSE 

1  NESTED  CONDITIONAL 

HONORED  WITHIN  NESTED.  UNSATISFIED 
f CONDITIONAL  BLOCK 

• 

,  IFT 
• 

»N0T  SEEN 

• 

.ENDC 

.ENDC 

.IF 

.IF 

.IFF 

• 

OF  ,  X 

OF » Y 

1  TESTS  TRUE 

ITESTS  FALSE 

118  ASSEMBLED 

I0UTER  CONDITIONAL  SATISFIED. 

.IFT 


) NOT  ASSEMBLED 


.ENDC 

.ENOC 


5.5.11.2  Immediate  Conditionals  -  An  immediate  conditional  directive 
is  a  means  of  writing  a  1— line  conditional  block.  In  this  form,  no 
.ENDC  statement  is  required  and  the  condition  is  completely  expressed 
on  the  line  containing  the  conditional  directive.  Immediate 
conditions  are  of  the  form: 

. IIF  cond,  arg,  statement 

where:  cond  is  one  of  the  legal  conditions  defined  for 

conditional  blocks  in  Section  5.5.11. 


5-58 


MACRO  Assembler 


arg  is  the  argument  associated  with  the  conditional 

specified,  that  is,  either  an  expression,  symbol, 
or  macro-type  argument,  as  described  in  Section 
5.5.11. 

statement  is  the  statement  to  be  executed  if  the  condition 
is  met. 

For  example: 

.IIF  OF ,  FOO , BEQ  ALPHA 

This  statement  generates  the  code: 

BEQ  ALPHA 

if  the  symbol  FOO  is  defined. 

A  label  must  not  be  placed  in  the  label  field  of  the  .IIF  statement. 

Any  necessary  labels  may  be  placed  on  the  previous  line,  as  in  the 

following  example: 

LABEL  I 

.IIF  OF i FPP  BEQ  ALPHA 

or  included  as  part  of  the  conditional  statement: 

.IIF  OF, FOO  LABEL  I  BEQ  ALPHA 


5.5.11.3  PAL-11R  and  PAL-11S  Conditional  Assembly  Directives  -  In 
order  to  maintain  compatibility  with  programs  developed  under  PAL-11R 
and  PAL-11S,  the  following  conditionals  remain  permissible  under 
MACRO.  It  is  advisable  that  future  programs  be  developed  using  the 
format  for  MACRO  conditional  assembly  directives. 


Directive 


Arguments 


Assemble  Block  if 


. IFZ  or  . IFEQ 
. IFNZ  or.IFNE 
.IFL  or  . IFLT 
.IFG  or  . IFGT 
.IFGE 
.IFLE 
.IFDF 
. IFNDF 


expression 
expression 
expression 
expression 
expression 
expression 
logical  expression 
logical  expression 


expression-0 
expression#) 
express ion<0 
expressions 
expre s s ion= > 0 
express ion<=0 

expression  is  true (defined) 
expression  is  false (undefined) 


The  rules  governing  the  usage  of  these  directives  are  now  the  same  as 
for  the  MACRO  conditional  assembly  directives  previously  described. 
Conditional  assembly  blocks  must  end  with  the  .ENDC  directive  and  are 
limited  to  a  nesting  depth  of  16(10)  levels  (instead  of  the  127(10) 
levels  allowed  under  PAL-llR) . 
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5 . 6  MACRO  DIRECTIVES 


5.6.1  Macro  Definition 

It  is  often  convenient  in  assembly  language  programming  to  generate  a 
recurring  coding  sequence  with  a  single  statement.  In  order  to  do 
this,  the  desired  coding  sequence  is  first  defined  with  dummy 
arguments  as  a  macro.  Once  a  macro  has  been  defined,  a  single 
statement  calling  the  macro  by  name  with  a  list  of  real  arguments 
(replacing  the  corresponding  dummy  arguments  in  the  definition) 
generates  the  correct  sequence  or  expansion. 


5. 6. 1.1  .MACRO  -  The  first  statement  of  a  macro  definition  must  be  a 
.MACRO  directive  (not  available  in  ASEMBL) .  The  .MACRO  directive  is  of 
the  forms 


where  s 


.MACRO  name,  dummy  argument  list 


name  is  the  name  of  the  macro.  This  name  is  any  legal 

symbol.  The  name  chosen  may  be  used  as  a  label 
elsewhere  in  the  program. 

,  represents  any  legal  separator  (generally  a  comma 

or  space) . 


dummy 

argument 

list 


zero,  one,  or  more  legal  symbols  which  may  appear 
anywhere  in  the  body  of  the  macro  definition, 
even  as  a  label.  These  symbols  can  be  used 
elsewhere  in  the  user  program  with  no  conflicts  of 
definition.  Where  more  than  one  dummy  argument  is 
used,  they  are  separated  by  any  legal  separator 
(generally  a  comma) . 


A  comment  may  follow  the  dummy  argument  list  in  a  statement  containing 
a  .MACRO  directive.  For  example: 

.MACRO  ABS  A , B  I0EFINE  MACRO  ABS  WITH  TWO  ARGUMENTS 

A  label  must  not  appear  on  a  .MACRO  statement.  Labels  are  sometimes 
used  on  macro  calls,  but  serve  no  function  when  attached  to  .MACRO 
statements. 


5. 6. 1.2  .ENDM  -  The  final  statement  of  every  macro  definition  must 
be  an  .ENDM  directive  (not  available  in  ASEMBL)  of  the  form: 

.ENDM  name 

where  name  is  an  optional  argument  and  is  the  name  of  the  macro  being 
terminated  by  the  statement. 

For  example: 
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.ENDM  (terminates  the  current  macro  definition) 

.ENDM  ABS  (terminates  the  definition  of  the  macro  ABS) 

If  specified,  the  symbolic  name  in  the  .ENDM  statement  must  correspond 
to  that  in  the  matching  .MACRO  statement.  Otherwise  the  statement  is 
flagged  and  processing  continues.  Specification  of  the  macro  name  in 
the  .ENDM  statement  permits  the  assembler  to  detect  missing  .ENDM 
statements  or  improperly  nested  macro  definitions. 

The  .ENDM  statement  may  contain  a  comment  field,  but  must  not  contain 
a  label. 

An  example  of  a  macro  definition  is  shown  below: 

.MACRO  TYPM3G  MESSGE  I  TYPE  A  MESSAGE 
JSR  R5»  T YPMSG 
.WORD  MESSGE 
•  ENDM 


5. 6. 1.3  .MEXIT  -  In  order  to  implement  alternate  exit  points  from  a 
macro  (particularly  nested  macros) ,  the  .MEXIT  directive  is  provided. 
.MEXIT  (not  available  in  ASEMBL)  terminates  the  current  macro  as 
though  an  .ENDM  directive  were  encountered.  Use  of  .MEXIT  bypasses 
the  complications  of  conditional  nesting  and  alternate  paths.  For 
example : 


.MACRO 

• 

ALT* 

N,A,B 

• 

.IF 

t 

EQi  N 

ISTART  CONDITIONAL  BLOCK 

« 

.MEXIT 

JEXIT  FROM  MACRO  DURING  CONDITIONAL 
1  BLOCK 

,ENDC 

• 

fEND  CONDITIONAL  BLOCK 

• 

.ENOM 

^normal  end  of  macro 

In  an  assembly  where  N=0,  the  .MEXIT  directive  terminates  the  macro 
expansion. 

Where  macros  are  nested,  a  .MEXIT  causes  an  exit  to  the  next  higher 
level.  A  .MEXIT  encountered  outside  a  macro  definition  is  flagged  as 
an  error. 


5. 6. 1.4  Macro  Definition  Formatting  -  A  form  feed  character  used  as 
a  line  terminator  in  a  macro  source  statement  (or  as  the  only 
character  on  a  line) ,  causes  a  page  eject  when  the  source  program  is 
listed.  Used  within  a  macro  definition,  a  form  feed  character  also 
causes  a  page  eject.  A  page  eject  is  not  performed,  however,  when  the 
macro  is  invoked. 
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Used  within  a  macro  definition ,  the  .PAGE  directive  is  ignored ,  but  a 
page  eject  is  performed  at  invocation  of  that  macro. 


5.6.2  Macro  Calls 

A  macro  must  be  defined  prior  to  its  first  reference.  Macro  calls  are 
of  the  general  forms 

label:  name,  real  arguments 

where:  label  represents  an  optional  statement  label. 

name  represents  the  name  of  the  macro  specified  in  the 

•MACRO  directive  preceding  the  macro  definition. 

represents  any  legal  separator  (comma,  space ,  or 
tab) .  No  separator  is  necessary  where  there  are  no 
real  arguments.  (Refer  to  Section  5. 2. 1.1.) 

real  arguments 

are  those  symbols ,  expressions ,  and  values  which 
replace  the  dummy  arguments  in  the  .MACRO 
statement.  Where  more  than  one  argument  is  used, 
they  are  separated  by  any  legal  separator. 

Where  a  macro  name  is  the  same  as  a  user  label,  the  appearance  of  the 
symbol  in  the  operation  field  designates  a  macro  call,  and  the 


occurrence  of  the  symbol 
reference.  For  example: 

in  the 

operand 

field 

designates 

a  label 

ABSI 

MOV 

• 

»R0,R1 

MBS  IS 

USED  AS  A 

LABEL 

• 

BR 

• 

ASS 

IASS  IS 

CONSIDERED 

A  LABEL 

• 

A0S 

#«,£NT, 

LAR 

/CALL  MACRO  WITH  3 

ARGUMENTS 

Arguments  to  the  macro  call  are  treated  as  character  strings  whose 
usage  is  determined  by  the  macro  definition. 


5.6.3  Arguments  to  Macro  Calls  and  Definitions 

Arguments  within  a  macro  definition  or  macro  call  are  separated  from 
other  arguments  by  any  of  the  separating  characters  described  in 
Section  5. 2. 1.1.  For  example: 

.MACRO  REN  A , B , C  JMACRO  DEFINITION 

REN  alpha, BETA, <C1,C2>  /macro  call 


5-62 


MACRO  Assembler 


Arguments  which  contain  separating  characters  are  enclosed  in  paired 
angle  brackets.  An  up-arrow  construction  is  provided  to  allow  angle 
brackets  to  be  passed  as  arguments . 

For  example: 

REN  <M0  V  X,Y>,#4«,WEV 

This  call  would  cause  the  entire  statement: 

MOV  X, Y 

to  replace  all  occurrences  of  the  symbol  A  in  the  macro  definition. 
Real  arguments  within  a  macro  call  are  considered  to  be  character 
strings  and  are  treated  as  a  single  entity  until  their  use  in  the 
macro  expansion. 

The  up-arrow  construction  could  have  been  used  in  the  above  macro  call 
as  follows: 

REN  -/MOV  X,Y/,#44.WEV 

which  is  equivalent  to: 

REN  cMOV  X,  Y>,*«<t,NEV 

Since  spaces  are  ignored  preceding  an  argument,  they  can  be  used  to 
increase  legibility  of  bracketed  constructions. 


5. 6. 3.1  Macro  Nesting  -  Macro  nesting  (nested  macro  calls),  where  the 
expansion  of  one  macro  includes  a  call  to  another  macro,  causes  one 
set  of  angle  brackets  to  be  removed  from  an  argument  with  each  nesting 
level.  The  depth  of  nesting  allowed  is  dependent  upon  the  amount  of 
memory  space  used  by  the  program.  To  pass  an  argument  containing 
legal  argument  delimiters  to  nested  macros,  the  argument  should  be 
enclosed  in  one  set  of  angle  brackets  for  each  level  of  nesting,  as 
shown  below: 

R0»X0 

Ri«*l 

XM0 


.MACRO  IEVEL1  DUM1 ,  0UM2 
levels  DUM 1 
LEVELS  DUM2 
.ENOM 

.MACRO  LEVELS  0UM3 
DUM3 

ADO  *10, R0 

MOV  R0,  ( R 1 5  * 

.ENOM 

A  call  to  the  LEVEL1  macro: 

LEVEL  1  <«M0V  X,R0>>,«<CLR  R0>> 

causes  the  following  expansion: 
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MOV 

X ,  R0 

ADD 

#10#R0 

MOV 

R0,  (RD* 

CLR 

R0 

ADD 

#10*R0 

MOV 

R0, C  R 1 ) ♦ 

Where  macro  definitions  are  nested  (that  is,  a  macro  definition  is 
entirely  contained  within  the  definition  of  another  macro)  the  inner 
definition  is  not  defined  as  a  callable  macro  until  the  outer  macro 
has  been  called  and  expanded.  For  example: 


MACRO 

L  V 1 

• 

• 

MACRO 

LV2 

• 

• 

ENDM 

ENDM 

The  LV2  macro  cannot  be  called  by  name  until  after  the  first  call  to 
the  LV1  macro.  Likewise,  any  macro  defined  within  the  LV2  macro 
definition  cannot  be  referenced  directly  until  LV2  has  been  called. 


5. 6. 3. 2  Special  Characters  -  Arguments  may  include  special  characters 
without  enclosing  the  argument  in  a  bracket  construction  if  that 
argument  does  not  contain  spaces,  tabs,  semicolons,  or  commas.  For 
example : 

.MACRO  PUSH  ARC 
MOV  ARC,-(SP) 

.Endm 

PUSH  X+3CX2) 

generates  the  following  code: 

MOV  Xt3 (X2) * • (SP) 


5.6. 3. 3  Numeric  Arguments  Passed  as  Symbols  -  When  passing  macro 
arguments,  a  useful  capability  is  to  pass  a  symbol  which  can  be 
treated  by  the  macro  as  a  numeric  string.  An  argument  preceded  by  the 
unary  operator  backslash  (\)  is  treated  as  a  number  in  the  current 
radix.  (\  is  not  available  in  ASEMBL.)  The  ASCII  characters 
representing  the  number  are  inserted  in  the  macro  expansion;  their 
function  is  defined  in  context  (see  Section  5.6. 3.6  for  an  explanation 
of  single-quote  usage).  For  example: 
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A'Bl 


.MACRO 

CNT 

.WORD 

.ENDM 

C»0 

.MACRO 

INC 

CNT 

A.  SB 

A  *  B 


A»B 


8«B*l 

.ENDM 


INC 


x>c 


The  macro  call  would  expand  to: 

X0I  , WORD 

A  subsequent  identical  call  to  the  same  macro  would  generate: 

X 1 1  .WORD 

and  so  on  for  later  calls.  The  two  macros  are  necessary  because  the 
dummy  value  of  B  cannot  be  updated  in  the  CNT  macro.  In  the  CNT 
macro,  the  number  passed  is  treated  as  a  string  argument.  (Where  the 
value  of  the  real  argument  is  0,  a  single  0  character  is  passed  to  the 
macro  expansion.) 

The  number  being  passed  can  also  be  used  to  make  source  listings 
somewhat  clearer.  For  example,  versions  of  programs  created  through 
conditional  assembly  of  a  single  source  can  identify  themselves  as 
follows : 


.MACRO 

I0T 

.IDENT 

/SYM/ 

.ENDM 

I0T 

.MACRO 

OUT 

I0T 

005A»ARG 

.ENDM 

• 

0 

0 

OUT 

SIO 

SYM 


ARC 


I  ASSUME  THAT  THE  SYMBOL  ID  TAKES 
I ON  A  UNIQUE  2  DIGIT  VALUE  FOR 
fEACH  POSSIBLE  CONDITIONAL 
I ASSEMBLY  OF  THE  PROGRAM 


INHERE  005A  IS  THE  UPDATE  VERSION 
I  OF  THE  PROGRAM  AND  ARG  INDICATES 
ITHE  CONDITIONAL  ASSEMBLY  VERSION 

The  above  macro  call  expands  to: 

.IDENT  /005AXX/ 

where  XX  is  the  conditional  value  of  ID. 

Two  macros  are  necessary  since  the  text  delimiting  characters  in  the 
•IDENT  statement  would  inhibit  the  concatenation  of  a  dummy  argument. 
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5. 6. 3. 4  Number  of  Arguments  -  If  more  arguments  appear  in  the  macro 
call  than  in  the  macro  definition,  the  excess  arguments  are  ignored. 
If  fewer  arguments  appear  in  the  macro  call  than  in  the  definition, 
missing  arguments  are  assumed  to  be  null  (consist  of  no  characters) . 
The  conditional  directives  .IF  B  and  .IF  NB  can  be  used  within  the 
macro  to  detect  null  arguments. 

A  macro  can  be  defined  with  no  arguments. 


5. 6. 3. 5  Automatically  Created  Symbols  Within  User-Defined  Macros  - 
MACRO  can  be  made  to  create  symbols  of  the  form  n$  where  n  is  a 
decimal  integer  number  such  that  64<n<127.  Created  symbols  are  always 
local  symbols  between  64$  and  127$.  Such  local  symbols  are  created  by 
the  assembler  in  numerical  order,  i.e.: 

64$ 

65$ 


126$ 

127$ 

Created  symbols  are  particularly  useful  where  a  label  is  required  in 
the  expanded  macro.  Such  a  label  must  otherwise  be  explicitly  stated 
as  an  argument  with  each  macro  call  or  the  same  label  is  generated 
with  each  expansion  (resulting  in  a  multiply-defined  label) .  Unless  a 
label  is  referenced  from  outside  the  macro,  there  is  no  reason  for  the 
programmer  to  be  concerned  with  that  label. 

The  range  of  these  local  symbols  extends  between  two  explicit  labels. 
Each  new  explicit  label  causes  a  new  local  symbol  block  to  be 
initialized. 

The  macro  processor  creates  a  local  symbol  on  each  call  of  a  macro 
whose  definition  contains  a  dummy  argument  preceded  by  the  ? 
character.  For  examples 


.MACRO 

ALPHA 

TST 

A 

BEQ 

B 

ADD 

#  5  t  A 

Si 

.ENDM 


Local  symbols  are  generated  only  where  the  real  argument  of  the  macro 
call  is  either  null  or  missing.  If  a  real  argument  is  specified  in 
the  macro  call,  the  generation  of  a  local  symbol  is  inhibited  and 
normal  replacement  is  performed.  Consider  the  following  expansions  of 
the  macro  ALPHA  above. 
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Generate  a  local  symbol  for  missing  argument: 

ALPHA  XI 

T5T  XI 

BEQ  60S 

ADD  #5, XI 

feasi 

Do  not  generate  a  local  symbol: 

ALPHA  X2#  XYZ 

TST  X2 

BEQ  XYZ 

ADD  *5,X2 


These  assembler-generated  symbols  are  restricted  to  the  first  sixteen 
(decimal)  arguments  of  a  macro  definition. 


5. 6. 3. 6  Concatenation  -  The  apostrophe  or  single  quote  character  (') 
operates  as  a  legal  separating  character  in  macro  definitions.  An  ' 
character  which  precedes  and/or  follows  a  dummy  argument  in  a  macro 
definition  is  removed,  and  the  substitution  of  the  real  argument 
occurs  at  that  point.  For  example: 

.MACRO  def  a,b,c 
A  *8  J  .ASCIZ  /C/ 

.WORO  "A*»*B 
.ENDM 

When  this  macro  is  called: 

DEF  X,  Y,<MACR0-ii> 

it  expands  as  follows: 

XYI  .ASCIZ  /MACRO-11/ 

.WORD  *  X  *  Y 

In  the  macro  definition,  the  scan  terminates  upon  finding  the  first  ' 
character.  Since  A  is  a  dummy  argument,  the  '  is  removed.  The  scan 
resumes  with  B,  notes  B  as  another  dummy  argument  and  concatenates  the 
two  dummy  arguments.  The  third  dummy  argument  is  noted  as  going  into 
the  operand  of  the  .ASCIZ  directive.  On  the  next  line  (this  example 
is  for  purely  illustrative  purposes)  the  argument  to  .WORD  is  seen  as 
follows:  The  scan  begins  with  a  *  character.  Since  it  is  neither 
preceded  nor  followed  by  a  dummy  argument,  the  '  character  remains  in 
the  macro  definition.  The  scan  then  encounters  the  second  '  character 
which  is  followed  by  a  dummy  argument  and  is  discarded.  The  scan  of 
the  argument  A  terminates  upon  encountering  the  second  •  which  is  also 
discarded  since  it  follows  a  dummy  argument.  The  next  '  character  is 
neither  preceded  nor  followed  by  a  dummy  argument. and  remains  in  the 
macro  expansion.  The  last  '  character  is  followed  by  another  dummy 
argument  and  is  discarded.  (Note  that  the  five  '  characters  were 
necessary  to  generate  two  '  characters  in  the  macro  expansion.) 

Within  nested  macro  definitions,  multiple  single  quotes  can  be  used, 
with  one  quote  removed  at  each  level  of  macro  nesting. 


5-67 


MACRO  Assembler 


5.6.4  .NARG,  .NCHR,  and  .NTYPE 

These  three  directives  allow  the  user  to  obtain  the  number  of 
arguments  in  a  macro  call  (.NARG),  the  number  of  characters  in  an 
argument  (.NCHR),  or  the  addressing  mode  of  an  argument  (.NTYPE). 
(They  are  not  available  in  ASEMBL.)  Use  of  these  directives  permits 
selective  modifications  of  a  macro  depending  upon  the  nature  of  the 
arguments  passed. 

The  .NARG  directive  enables  the  macro  being  expanded  to  determine  the 
number  of  arguments  supplied  in  the  macro  call  and  is  of  the  form: 

label:  .NARG  symbol 

where:  label  is  an  optional  statement  label 

symbol  is  any  legal  symbol  which  is  equated  to  the  number 
of  arguments  in  the  macro  call  currently  being 
expanded.  The  symbol  can  be  used  by  itself  or  in 
expressions. 

This  directive  can  occur  only  within  a  macro  definition.  An  example 


of  the  use  of  .NARG  follows. 

.MACRO 

ARGS  A  1 , A2, A3, AA 

.NARG 

NUM 

.if  eo 

NUM.l  » I F  A2,  A3,  A A 

1  NOT  SPECIFIED 

WERE 

.WORD 

A I 

.IFF 

1  IF  ALL  ARGS  MERE  GIVEN 

.WORD 

A  1 

.ASCII 

/  A2/ 

.WORD 

A3 

.ASCII 

.ENDC 

.ENOM 

/A  A/ 

ARCS 

ALPHA 

.WORD 

ALPHA 

generated 

ARGS 

ALPHA, BETA, GAMMA, DELTA 

.WORD 

ALPHA 

generated 

.ASCII 

/BETA/ 

.WORD 

GAMMA 

.ASCII 

/DELTA/ 

The  .NCHR  directive  enables  a  program  to  determine  the  number  of 
characters  in  a  character  string,  and  is  of  the  form: 


label:  .NCHR  symbol,  < character  string> 

where:  label  is  an  optional  statement  label 

symbol  is  any  legal  symbol  which  is  equated  to  the  number 
of  characters  in  the  specified  character  string. 
The  symbol  is  separated  from  the  character  string 
argument  by  any  legal  separator. 
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< character  string > 

is  a  string  of  printing  characters  which  should 
only  be  enclosed  in  angle  brackets  if  it  contains 
a  legal  separator.  A  semicolon  also  terminates 
the  character  string. 

This  directive  can  occur  anywhere  in  a  MACRO  program.  For  example: 


.MACRO 

CHARS  * 

.  NCHR 

NUM,  A 

.ASCII 

/A/ 

.IP  EQ 

NUMtl 

IIP  THE  STRING  CONTAINS 
IAN  EVEN  NUMBER  OP 

icharacters 

.WORO 

•  l 

.  IP  P 
.byte 

.ENDC 
,  ENOM 

•  2 

IIP  STRING  LENGTH  IS  000 

For  example,  using  the  above  definition,  the  code: 

CHARS  ALPHA 

expands  to: 

.ASCII  /ALPHA/ 

.BYTE  -2 

and 


CHARS  BETA 

expands  to: 

.ASCII  /BETA/ 

.WORD  -1 

The  .NTYPE  directive  enables  the  macro  being  expanded  to  determine  the 
addressing  mode  and  register  of  any  argument,  and  is  of  the  form: 


label:  .NTYPE  symbol,  arg 


where:  label  is  an  optional  statement  label 

symbol  is  any  legal  symbol,  the  low  order  6-bits  of  which 
is  equated  to  the  6-bit  addressing  mode  of  the 
argument.  The  symbol  is  separated  from  the 
argument  by  a  legal  separator.  This  symbol  can  be 
used  by  itself  or  in  expressions. 

arg  is  any  legal  macro  argument  (dummy  argument)  as 

defined  in  Section  5.6.3. 

This  directive  can  occur  only  within  a  macro  definition.  An  example 
of  .NTYPE  usage  in  a  macro  definition  is  shown  below: 
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.MACRO 

SAVE  ARG 

, NT YPE 

SYM, ARG 

.IF 

EU,SYMi70 

MOV 

.IFF 

ARG, TEMP 

IREGISTER  MODE 

MOV 

,£NDC 

.ENOM 

#ARG , TEMP 

IKON-REGISTER  MODE 

Using  this  definition,  the  code: 

SAVE  R2 

expands  to ; 

MOV  #R2,TEMp 

and 

SAVE  ALPHA 

expands  to: 


MOV  PALPHA » TEMP 


5.6.5  .ERROR  and  .PRINT 

The  .ERROR  directive  (not  available  in  A5EMBL)  is  used  to  output 
messages  to  the  listing  file  during  assembly  pass  2.  A  common  use  is 
to  provide  diagnostic  announcements  of  a  rejected  or  erroneous  macro 
call.  The  form  of  the  .ERROR  directive  is  as  follows: 


label:  .ERROR  expr;text 


where:  label  is  an  optional  statement  label 


expr  is  an  optional  legal  expression  whose  value  is 

output  to  the  listing  file  when  the  .ERROR 
directive  is  encountered.  Where  expr  is  not 
specified,  the  text  only  is  output  to  the  listing 
file. 


;  denotes  the  beginning  of  the  text  string  to  be 

output. 

text  is  the  string  to  be  output  to  the  listing  file. 

The  text  string  is  terminated  by  a  line 
terminator. 

Upon  encountering  a  .ERROR  directive  anywhere  in  a  MACRO  program,  the 
assembler  outputs  a  single  line  containing: 

1.  the  sequence  number  of  the  .ERROR  directive  line, 

2.  the  current  value  of  the  location  counter, 

3.  the  value  of  the  expression  if  one  is  specified,  and. 
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4.  the  text  string  specified. 

For  example,  assume  the  following  error  macro  occurs: 

.MACRO  STORE  SRC, DEST 
.NTYPE  A , DEST 

.IF  EQ,«A«,7*-6  HF  STACK  POINTER  USED 
.ERROR  AJUMACCEPTABLE  MACRO  ARGUMENT 

.IFF 

MOV  SRC.OtST 

,  ENDC 

,EN0M 


STORE  R3,#«(SP) 

and  the  following  line  is  output: 

******  P 

00000  000076  .ERROR  A I  UNACCEPTABLE  MACRO  ARGUMENT 

This  message  is  used  to  indicate  an  inability  of  the  subject  macro  to 
cope  with  the  argument  DEST  which  is  detected  as  being  indexed 
deferred  addressing  mode  (mode  70)  with  the  stack  pointer  (%6)  used  as 
the  index  register.  The  line  is  flagged  on  the  assembly  listing  with 
a  P  error  code. 

The  .PRINT  directive  is  identical  to  .ERROR  except  that  it  is  not 
flagged  with  a  P  error  code.  (.PRINT  is  not  available  in  ASEMBL.) 


5.6.6  Indefinite  Repeat  Block:  .IRP  and  .IRPC 

An  indefinite  repeat  block  (not  available  in  ASEMBL)  is  a  structure 
very  similar  to  a  macro  definition.  An  indefinite  repeat  is 
essentially  a  macro  definition  which  has  only  one  dummy  argument  and 
is  expanded  once  for  every  real  argument  supplied.  An  indefinite 
repeat  block  is  coded  in-line  with  its  expansion  rather  than  being 
referenced  by  name  as  a  macro  is  referenced.  An  indefinite  repeat 
block  is  of  the  form: 


label: 


.IRP  arg, <real  arguments > 


(range  of  the  indefinite  repeat) 


where:  label 


arg 


.  ENDM 

is  an  optional  statement  label.  A  label  may  not 
appear  on  any  .IRP  statement  within  another  macro 
definition,  repeat  range  or  indefinite  repeat 
range,  or  on  any  .ENDM  statement. 

is  a  dummy  argument  which  is  successively  replaced 
with  the  real  arguments  in  the  .IRP  statement. 
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<real  arguments > 

is  a  list  of  arguments  to  be  used  in  the  expansion 
of  the  indefinite  repeat  range  and  enclosed  in 
angle  brackets.  Each  real  argument  is  a  string  of 
zero  or  more  characters  or  a  list  of  real 
arguments  (enclosed  in  angle  brackets) .  The  real 
arguments  are  separated  by  commas. 

range  is  the  code  to  be  repeated  once  for  each  real 
argument  in  the  list.  The  range  may  contain  macro 
definitions,  repeat  blocks,  or  other  indefinite 
repeat  blocks.  Note  that  only  created  symbols 
should  be  used  as  labels  within  an  indefinite 
repeat  range. 

An  indefinite  repeat  block  can  occur  either  within  or  outside  macro 
definitions,  repeat  ranges,  or  indefinite  repeat  ranges.  The  rules 
for  creating  an  indefinite  repeat  block  are  the  same  as  for  the 
creation  of  a  macro  definition  (for  example,  the  .MEXIT  statement  is 
allowed  in  an  indefinite  repeat  block).  Indefinite  repeat  arguments 
follow  the  same  rules  as  macro  arguments.  A  second  type  of  indefinite 
repeat  block  is  available  which  handles  character  substitution  rather 
than  argument  substitution.  The  .IRPC  directive  is  used  as  follows: 

label:  .IRPC  arg, string 


(range  of  indefinite  repeat) 


.ENDM 

On  each  iteration  of  the  indefinite  repeat  range,  the  dummy  argument 
(arg)  assumes  the  value  of  each  successive  character  in  the  string. 
Terminators  for  the  string  are:  space,  comma,  tab,  carriage  return, 
line  feed,  and  semicolon. 

Figure  5-6  is  an  example  of  .IRP  and  .IRPC  usage. 


IRPTST  RT-li  MACRO  VM02-09  11104149  PAGE  1 


1 

2 

3 

4 

5 

6 
7 

e 

9  000000 


10  0  0  0  (9  0 
012700 
000056  r 


.TITLE  IRPTST 
.LIST  MD,MC,ME 
R0*  X0 

MOV  #T  ABLE i H0 
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10 

ti 

12 

13 

00004  016720 
000032 

00010  016720 
000030 

00014  016720 
000026 

00020  016720 
000024 

00024  016720 
000022 

00030  016720 
000020 

14 

15 

16 

00034  101 

00035  102 

00036  103 

00037  104 

00040  105 

00041  106 

17 

16  00042  041101  A ! 

19  00044  041502  Bl 

20  00046  042103  Cl 

21  00050  042504  D I 

22  00052  043105  El 

23  00054  043506  FI 

24  00056  TABtEI 

25  000001* 


.IRP 

X , « A »  B# C » D»  E » F> 

MOV 

,EN0M 

X, (R0)* 

MOV 

A  t  (R0)  + 

MOV 

B, (R0)  * 

MOV 

C*  C«0)A 

MOV 

0' (R0)  ♦ 

MOV 

E, (R0)  * 

MOV 

F, (R0) ♦ 

•  IRPC 

X  f ABCDEF 

.ASCII 

/X/ 

.ENDM 

.ASCII 

/A/ 

.ASCII 

/B/ 

.ASCII 

/C/ 

.ASCII 

/P/ 

.ASCII 

/£/ 

.ASCII 

tft 

.WORD 

"AB 

.WORD 

"8C 

.WORD 

"CO 

.WORD 

"DE 

.WORD 

"EF 

.WORD 

"FC 

.BLKW 

6 

.  ENO 

Figure  5-6 

. ZRP  and  . IRPC  Example 


5.6.7  Repeat  Block:  .REPT 

Occasionally  it  is  useful  to  duplicate  a  block  of  code  a  number  of 
times  in  line  with  other  source  code.  (.REPT  is  not  available  in 
ASEMBL.)  This  is  performed  by  creating  a  repeat  block  of  the  form: 

label:  .REPT  expr 


(range  of  repeat  block) 
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where:  label 


expr 


range 


.ENDM  ;OR  .ENDR 

is  an  optional  statement  label.  The  .ENDR  or 
.ENDM  directive  may  not  have  a  label.  A  .REPT 
statement  occurring  within  another  repeat  block, 
indefinite  repeat  block,  or  macro  definition  may 
not  have  a  label  associated  with  it. 

is  any  legal  expression  controlling  the  number  of 
times  the  block  of  code  is  assembled.  Where 
expr<0,  the  range  of  the  repeat  block  is  not 
assembled. 

is  the  code  to  be  repeated  expr  number  of  times. 
The  range  may  contain  macro  definitions, 
indefinite  repeat  blocks,  or  other  repeat  blocks. 
Note  that  no  statements  within  a  repeat  range  can 
have  a  label. 


The  last  statement  in  a  repeat  block  can  be  an  .ENDM  or  .ENDR 
statement.  The  .ENDR  statement  is  provided  for  compatibility  with 
previous  assemblers. 


The  .MEXIT  statement  is  also  legal  within  the  range  of  a  repeat  block. 


5.6.8  Macro  Libraries:  .MCALL 

All  macro  definitions  must  occur  prior  to  their  referencing  within  the 
user  program.  MACRO  provides  a  selection  mechanism  for  the  programmer 
to  indicate  in  advance  those  system  macro  definitions  required  by  his 
program. 

The  .MCALL  directive  is  used  to  specify  the  names  of  all  system  macro 
definitions  not  defined  in  the  current  program  but  required  by  the 
program  (not  available  in  ASEMBL) .  The  .MCALL  directive  must  appear 
before  the  first  occurrence  of  a  macro  call  for  an  externally  defined 
macro.  The  .MCALL  directive  is  of  the  form: 

.MCALL  argl,arg2,... 

where  argl,arg2,  etc.  are  the  names  of  the  macro  definitions  required 
in  the  current  program. 

When  this  directive  is  encountered,  MACRO  searches  the  system  library 
file  SYSMAC.SML,  to  find  the  requested  definition (s) .  MACRO  searches 
for  SYSMAC.SML  on  the  system  device. 

See  Appendix  D  for  a  listing  of  the  system  macro  file  (SYSMAC.SML) 
stored  on  the  system  device. 


5.7  CALLING  AND  USING  MACRO 

The  MACRO  Assembler  assembles  one  or  more  ASCII  source  files 
containing  MACRO  statements  into  a  single  relocatable  binary  object 
file.  Assembler  output  consists  of  this  binary  object  file  and  an 
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optional  assembly  listing  followed  by  the  symbol  table  listing.  CREF 
(Cross  Reference)  listings  may  also  be  specified  as  part  of  the 
assembly  output  by  means  of  switch  options. 


MACRO  is  executed  using  the  RT-11  Monitor  R  command  as  follows: 
.R  MACRO 


The  assembler  responds  by  typing  an  asterisk  (*)  to  indicate  readiness 
to  accept  command  string  input.  In  response  to  the  *  printed  by  the 
assembler,  the  user  types  the  output  file  specification (s) ,  followed 
by  an  equal  sign  or  left  angle  bracket,  followed  by  the  input  file 
specification (s)  in  a  command  line  as  follows: 


*dev:obj  9 dev: list/s :arg-dev:sourcel# . . #dev:sourcen/s :arg 


where: 


dev: 

obj 

list 


is  any  legal  RT-11  device 
is  the  binary  object  file 


is  the  assembly  listing  file  containing 
the  assembly  listing  and  symbol  table 


sourcel, 

• • ,s ourcen 


are  the  ASCII  source  files  containing 
the  macro  source  program (s) ;  a  maximum 
of  six  source  files  is  allowed 

represents  a  switch  and  argument  as 
explained  in  Section  5.7.1 

A  null  specification  in  either  of  the  output  file  fields  signifies 
that  the  associated  output  file  is  not  desired. 


/s :arg 


One  or  more  switches  can  be  indicated  with  the  appropriate  file 
specification  to  provide  MACRO  with  information  about  that  file. 


The  default  case  for  each  file  specification  is  noted  below: 


file 

device 

filename 

extei 

object 

DK: 

- 

.OBJ 

listing 

device  used 
for  object 
output 

— 

•  LST 

sourcel 

DK: 

- 

.MAC 

source2 

• 

• 

device  used  - 

for  last  source 
file  specified 

.MAC 

sourcen 

system 

macro 

file 

system  device 
SY: 

SYSMAC 

•  SML 

Type  CTRL  C  to  halt  MACRO  at  any  time  and  return  control  to  the 
monitor.  To  restart  the  assembler  type  R  MACRO  or  the  REENTER  command 
in  response  to  the  monitor's  dot. 
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NOTE 

If  fC  was  typed  while  a  CREF  listing  was 
being  produced,  the  REENTER  command  may 
not  be  accepted.  In  this  case,  type  R 
MACRO  to  restart  the  assembler. 


5.7.1  Switches 

There  are  three  types  of  switch  options:  listing  control  switches, 
function  switches,  and  CREF  specification  switches.  The  luting 
control  switches  (/L,/N)  provide  capabilities  similar  to  those 
described  in  detail  in  section  5.5. 1.1.  The  function  control  switches 
(/D ,/E)  provide  function  control  as  described  in  Section  5.5.2; 
arguments  for  these  switches  are  summarized  in  Section  5. 7. 1.2.  CREF 
control  switches  allow  the  user  to  obtain  a  detailed  cross-referenced 
listing  of  his  assembled  file,  and  are  described  in  detail  m  Section 
5. 7. 1.3.  Multiple  arguments  may  be  specified  for  a  particular  switch, 
if  desired,  by  separating  each  switch  value  from  the  next  by  a  colon. 
For  example: 


/N:TTM:CND 

These  switches  turn  off  teleprinter  mode  and  suppress  printing  of 
unsatisfied  conditionals  (as  described  in  the  next  section) .Also,  the 
switches  are  not  restricted  to  appearing  near  a  particular  file  in  the 
command  string;  /N : TTM ,  for  example,  is  legal  in  all  of  the  following 
places : 

* , LP : /N : TTM=source 
* ,  LP : =source/N : TTM 
* /N : TTM , LP : ^source 

and  they  are  all  equivalent  in  function. 


5. 7. 1.1  Listing  Control  Switches  -  A  listing  control  switch  (/L  for 
list  or  /N  for  nolist)  is  indicated  in  a  command  line  as  follows: 

*dev : ob j . ext , dev : lis t . ext/s : arg=dev : source . ext 

where  s:arg  represents  /L  or  /N;  the  remainder  of  the  command  line 
abbreviations  are  as  described  in  Section  5.7. 


The  /N  switch  with  no  argument  causes  only  the  symbol  table  and  error 
listings  to  be  produced.  The  /L  switch  with  no  arguments  causes  .LIST 
and  .NLIST  directives  that  appear  in  the  source  program  but  have  no 
arguments  to  be  ignored.  A  summary  of  the  arguments  which  are  valid 
for  the  listing  control  switches  follows  (refer  to  Section  5. 5. 1.1  for 
details) : 


Argument  Default 


Controls  listing  of 


SEQ 

list 

LOC 

list 

BIN 

list 

BEX 

list 

Source  line  sequence  numbers 
Location  counter 
Generated  binary  code 
Binary  extensions 
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SRC 

list 

Source  code 

COM 

list 

Comments 

MD 

list 

Macro  definitions ,  repeat 
range  expansions 

MC 

list 

Macro  calls,  repeat  range  expansions 

ME 

nolist 

Macro  expansions 

MEB 

nolist 

Macro  expansion  binary  code 

CND 

list 

Unsatisfied  conditionals,  .IF  and 
.ENDC  statements 

LD 

nolist 

Listing  directives  with  no  arguments 

TOC 

list 

Table  of  Contents 

TTM 

terminal  mode 

Listing  output  format 

SYM 

list 

Symbol  table 

For  example,  a  command  line  in  the  following  format  allows  binary  code 
to  be  listed  throughout  the  assembly  using  the  132-column  line  printer 
format  s 

* , LP : /L : MEB/N  s  TTM=FILE 


5. 7. 1.2  Function  Switches  -  The  function  control  switches  (/D  for 
disable  and  /E  for  enable)  are  used  to  enable  or  disable  certain 
functions  in  source  input  files  and  are  indicated  in  the  command  line 
as  follows: 

*dev : ob j . ext , dev : lis t . ext=de v : source /s : arg 

/s:arg  here  represents  either  /Dsarg  or  /E:arg.  A  summary  of  the 
arguments  which  are  valid  for  use  with  the  function  control  switches 
follows  (refer  to  Section  5.5.2  for  details): 


Argument 

Default 

Enables  or  disables 

ABS 

disable 

Absolute  binary  output 

AMA 

disable 

Assembly  of  all  absolute  addresses 
as  relative  addresses 

CDR 

disable 

Source  columns  73  and  greater  to  be 
treated  as  comments 

FPT 

disable 

Floating  point  truncation 

LC 

disable 

Accepts  lower  case  ASCII  input 

LSB 

disable 

Local  symbol  lock 

PNC 

enable 

Binary  output 

The  following  command  line  allows  all  80  columns  of  a  card  to  be  used 
as  input: 

*,LP:=CR:/E:CDR 

Use  of  either  the  function  control  or  listing  control  switches  and 
arguments  at  assembly-time  will  override  any  corresponding  listing  or 
function  control  directives  and  arguments  in  the  source  program.  For 
example,  assume  the  following  appears  in  the  source  program: 

.NLXST  MEB 

•  MACRO  References 

•LIST  MEB 
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The  "MEB"  printing  will  be  disabled  for  the  block  indicated;  however, 
if  /LsMEB  is  indicated  in  the  assembly  command  line,  both  the  .NLIST 
MEB  and  the  .LIST  MEB  will  be  ignored  and  the  "MEB"  printing  will  be 
enabled  everywhere  in  the  program. 


5. 7.1. 3  Cross  Reference  Table  Generation  (CREF)  -  A  cross  reference 
table  of  all  or  a  subset  of  all  symbols  used  in  the  source  program  and 
the  statements  where  they  were  defined  or  used  can  be  obtained 
automatically  following  an  assembly  by  specifying  /Csarg  with  the 
assembly  listing  file  specification  (and  any  listing  or  function 
control  specifications)  as  follows: 

*dev : ob j . ext , dev : lis t . ext/s : arg/C : arg=dev : source . ext 
/ssarg  represents  /L:arg,  /N:arg,  /E:arg,  or  /Dsarg. 

There  are  six  sections  to  a  complete  cross  reference  listing: 

1.  Cross  reference  of  program  symbols  (i.e.,  labels  used  in  the 
program  and  symbols  used  on  the  left  of  the  "="  operator) . 

2.  Cross  reference  of  register-equate  symbols  (those  symbols 
which  are  defined  in  the  program  by  a  "SYMBOL=%N" ,  0<=N<=7, 
construct.  (Normally  this  consists  of  the  symbols  RO,  Rl, 
R2 ,  R3 ,  R4,  R5,  SP,  and  PC.) 

3.  Cross  reference  of  MACRO  symbols  (names  of  macros  as  defined 
by  a  .MACRO  directive,  or  as  specified  in  a  • MC ALL 
directive) . 

4.  Cross  reference  of  permanent  symbols  (all  operation  mnemonics 
and  assembler  directives) . 

5.  Cross  reference  of  control  sections  (those  names  specified  as 
the  operand  of  a  .CSECT  directive,  plus  the  blank  .CSECT  and 
the  absolute  section  "•  ABS."  which  are  always  defined  by 
MACRO) . 

6.  Cross  reference  of  errors  (all  errors  flagged  on  the  listing 
are  grouped  by  error  type) . 

Any  or  all  of  the  above  sections  may  be  included  in  the  cross 
reference  listing  as  desired.  The  associated  switch  options  and  their 
arguments  are  listed  below: 


Switch 

Argument 

Section  Type 

/CsS 

User-defined  symbols 

/C:R 

Register  symbols 

/C:M 

Macro  symbolic  names 

/CsP 

Permanent  symbols 

/C:C 

( instructions ,  directives ) 
Control  sections  (.CSECT 

/C:E 

symbolic  names) 

Error  codes 

/C<no  arg> 

Equivalent  to  /C:S:M:E 
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The  specification  of  a  /C  switch  in  a  command  string  causes 
temporary  file,  "DKsCREF.TMP",  to  be  generated,  if  device  Sk?  is 
write-iocked  or  contains  insufficient  free  space  for  the  temporary 
file,  the  user  may  allocate  the  temporary  file  on  another  device  To 

string-3  ^his  fil^L^h®  sPecJffcation  ls  given  in  the  MACRO  coi^mand 
string,  this  file  is  then  used  instead  of  DKsCREF.TMP,  and  is  purged 
after  use.  For  example,  a  command  string  of  this  type:  P  9 

* , LP  s , RK2  s  TEMP . TMP=S OURCE /C 


causes  "RK2:TEMP.TMP"  to  be  used  as  the  temporary  file. 


Figure  5-7  illustrates  assembled  source  code  and  Figure 
the  CREF  output.  The  command  line  used  to  produce  these 


5-8  contains 
listings  was: 


*,LP:/C:S:H:R:P:C:E/N:BEX«EXAMPL 


An  explanation  of  the  CREF  output  follows  the  figures. 
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Cross  reference  tables,  if  requested,  are  generated  at  the  end  of  a 
MACRO  assembly  listing.  Each  table  begins  on  a  new  page  (the  tables 
in  Figure  5-8  have  been  consolidated  due  to  space  considerations) . 
Symbols,  control  sections,  and  error  codes  are  listed  at  the  left 
margin  of  the  page;  corresponding  references  are  indicated  next  to 
them  across  the  page  from  left  to  right.  A  reference  is  of  the  form 
p-1,  where  p  is  the  page  on  which  the  symbol,  control  section,  or 
error  code  appears,  and  1  is  the  line  number  within  the  page.  A 
number  sign  (#)  appears  next  to  a  reference  wherever  a  symbol  has  been 
defined.  An  asterisk  appears  next  to  a  reference  wherever  a 
destructive  reference  has  been  made  to  the  symbol  (i.e.,  the  contents 
of  the  location  defined  by  that  symbol  has  been  altered  at  that 
point) . 

The  CREF  output  requested  in  the  preceding  figures  included  user 
defined  symbols,  macro  symbolic  names,  control  sections,  error  codes, 
register  symbols,  and  permanent  symbols.  Since  no  errors  were 
generated  in  this  assembly,  no  CREF  output  for  error  codes  was 
produced. 


5 . 8  ERROR  MESSAGES 

MACRO  error  messages  enclosed  in  question  marks  are  output  on  the 
terminal.  The  single-letter  error  codes  are  printed  in  the  assembly 
listing. 

In  terminal  mode  these  error  codes  are  printed  following  a  field  of 
six  asterisk  characters  and  on  the  line  preceding  the  source  line 
containing  the  error.  For  example: 

******  ^ 

26  00236  000002'  .WORD  REL1+REL2 


Error  Code 


Meaning 


A  Addressing  error.  An  address  within  the  instruction  is 

incorrect.  Also  may  indicate  a  relocation  error.  The 
addition  of  two  relocatable  symbols  is  flagged  as  an  A 
error.  May  also  indicate  that  a  local  symbol  is  being 
defined  more  than  128  words  from  the  beginning  of  a 
local  symbol  block. 

B  Bounding  error.  Instructions  or  word  data  would  be 

assembled  at  an  odd  address  in  memory.  The  location 
counter  is  updated  by  +1. 

D  Doubly-defined  symbol  referenced.  Reference  was  made 

to  a  symbol  which  is  defined  more  than  once. 

E  End  directive  not  found.  (A  .END  is  generated.) 


I  Illegal  character  detected.  Illegal  characters  which 

are  also  non-printing  are  replaced  by  a  ?  on  the 
listing.  The  character  is  then  ignored. 

L  Line  buffer  overflow,  i.e.,  input  line  greater  them  132 

characters.  Extra  characters  on  a  line,  (more  than  72 
(10))  are  ignored  in  terminal  mode. 
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M  Multiple  definition  of  a  label.  A  label  was 

encountered  which  was  equivalent  (in  the  first  six 
characters)  to  a  previously  encountered  label. 

N  Number  containing  8  or  9  has  decimal  point  missing. 

0  Opcode  error.  Directive  out  of  context. 

P  Phase  error.  A  label's  definition  of  value  varies  from 

one  pass  to  another. 

Q  Questionable  syntax.  There  are  missing  arguments  or 

the  instruction  scan  was  not  completed  or  a  carriage 
return  was  not  immediately  followed  by  a  line  feed  or 
form  feed. 

R  Register-type  error.  An  invalid  use  of  or  reference  to 

a  register  has  been  made. 

T  Truncation  error.  A  number  generated  more  than  16  bits 

of  significance  or  an  expression  generated  more  than  8 
bits  of  significance  during  the  use  of  the  .BYTE 
directive. 

U  Undefined  symbol.  An  undefined  symbol  was  encountered 

during  the  evaluation  of  an  expression.  Relative  to 
the  expression,  the  undefined  symbol  is  assigned  a 
value  of  zero. 

Z  Instruction  which  is  not  compatible  among  all  members 

of  the  PDP-11  family  (11/05,  11/20,  11/40,  11/45). 


Error  Message 
?BAD  SWITCH? 

7INSUFFICIENT  CORE? 

?I/0  ERROR  ON  CHANNEL  n? 


?NO  INPUT  FILE? 


Explanation 


The  switch  specified  was  not 
recognized  by  the  program. 

There  are  too  many  symbols  in  the 
program  being  assembled.  Try 
dividing  program  into 
separately-assembled  subprograms . 

A  hardware  error  occurred  while 
attempting  to  read  from  or  write  to 
the  device  on  the  channel  specified 
in  the  message.  (Channel  numbers 
(0<**n<®10  octal)  are  assigned  to 
files  in  the  manner  described  in 
Section  9.4.7,  Chapter  9.) 

Note  that  the  CREF  temporary  file 
is  on  channel  2  even  if  it  was  not 
specified  in  the  command  string 
(i.e.,  if  the  default  file 
DKsCREF.TMP  is  used) . 

No  input  file  was  specified  and 
there  must  be  at  least  one  input 
file. 
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70UTPUT  DEVICE  FULL?  No  room  to  continue  writing  output. 

Try  to  compress  device  with  PIP, 


All  CREF  error  messages  begin  with  C-  to  distinguish  them  from  MACRO 
error  messages.  When  a  CREF  error  occurs ,  the  error  message  is 
printed  on  the  console  terminal  and  CREF  chains  back  to  MACRO;  MACRO 


prints  an  asterisk ,  at  which  time 
Error  Message 
?C- CHAIN- ONLY- CUSP? 

?C-CRF  FILE  ERROR? 

?C-DEVICE? 

7C-LST  FILE  ERROR? 


another  command  line  may  be  entered. 
Explanation 

An  attempt  was  made  either  to  "R 
CREF"  or  to  "START"  a  copy  of  CREF 
which  was  in  memory  due  to  a 
previous  MACRO  run  which  had 
chained  to  CREF  but  was  aborted 
from  the  console  terminal  (via 
CTRL  C) •  CREF  can  only  be  "chained" 
to;  it  cannot  be  invoked  without 
MACRO. 

An  output  error  occurred  while 
accessing  "DKjCREF.TMP" t  the 
temporary  file  passed  from  MACRO  to 
CREF. 

An  invalid  device  was  specified  to 
CREF  by  MACRO  (system  error) . 

An  output  error  occurred  while 
attempting  to  write  the 
cross-reference  table  to  the 
listing  file. 
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LINKER 


6 . 1  INTRODUCTION 

The  RT-11  Linker  converts  object  modules  produced  by  either  one  of  the 
RT-11  assemblers  or  FORTRAN  IV  into  a  format  suitable  for  loading  and 
execution.  This  allows  the  user  to  separately  assemble  a  main  program 
and  each  of  its  subroutines  without  assigning  an  absolute  load  address 
at  assembly  time.  The  object  modules  of  the  main  program  and 
subroutines  are  processed  by  the  Linker  to: 


1.  Relocate  each  object  module  and  assign  absolute  addresses 

2.  Link  the  modules  by  correlating  global  symbols  defined  in  one 
module  and  referenced  in  another  module 

3.  Create  the  initial  control  block  for  the  linked  program 

4.  Create  an  overlay  structure  if  specified  and  include  the 
necessary  run-time  overlay  handlers  and  tables 

5.  Search  user  specified  libraries  to  locate  unresolved  globals 

6.  Optionally  produce  a  load  map  showing  the  layout  of  the  load 
module 


The  RT-11  Linker  requires  two  or  three  passes  over  the  input  modules. 
During  the  first  pass  it  constructs  the  global  symbol  table,  including 
all  control  section  names  and  global  symbols  in  the  input  modules.  If 
library  files  are  to  be  linked  with  input  modules,  an  intermediate 
pass  is  needed  to  force  the  modules  resolved  from  the  •  library  file 
into  the  root  segment  (that  part  of  the  program  which  is  never 
overlaid).  During  the  final  pass,  the  Linker  reads  the  object  modules, 
performs  most  of  the  functions  listed  above,  and  produces  a  load 
module  (LDA  for  use  with  the  Absolute  Loader,  save  image  (SAV)  for  a 
Single-job  system  or  for  the  background  job  of  an  F/B  System,  and 
relocatable  (REL)  format  for  the  foreground  job  of  an  F/B  System) . 

The  Linker  requires  at  least  8K  of  memory;  any  additional  memory  is 
used  to  extend  the  symbol  table.  Input  is  accepted  from  any  binary 
device  on  the  system;  there  must  be  at  least  one  random  access  device 
(disk  or  DECtape)  for  save  image  or  relocatable  format  output. 
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6.2  CALLING  AND  USING  THE  LINKER 
To  call  the  Linker,  type  the  commands 
R  LINK 

and  the  RETURN  key  in  response  to  the  Keyboard  monitor's  dot.  The 
Linker  prints  an  asterisk  and  awaits  a  command  string. 

Type  CTRL  C  to  halt  the  Linker  at  any  time  and  return  control  to  the 
monitor.  To  restart  the  Linker,  type  R  LINK  or  the  REENTER  command  in 
response  to  the  monitor's  dot.  The  Linker  outputs  an  extra  line  feed 
character  when  it  is  restarted  with  REENTER  or  after  an  error  in  the 
first  command  line.  When  the  Linker  is  finished  linking,  control 
returns  to  the  CSI  automatically.  An  extra  line  feed  character 
precedes  the  asterisk  printed  by  the  CSI. 


6.2.1  Command  String 

The  first  command  string  entered  in  response  to  the  Linker's  asterisk 
has  the  following  format: 

*dev:binout,dev:mapout**dev:objl,dev:obj2 , . .  ,/sl/s2/s3 


where: 

is  a  random  access  device  for  the  save  image 
or  REL  format  output  file  (binout)  and  any 
appropriate  device  in  all  other  instances. 
If  dev:  is  not  specified,  DK  is  assumed.  If 
the  output  is  to  be  LDA  format  (that  is,  the 
/L  switch  was  used) ,  the  output  file  need  not 
be  on  a  random  access  device. 

is  the  name  to  be  assigned  to  the  Linker's 
save  image,  LDA  format,  or  REL  format  output 
file.  This  file  is  optional;  if  not 
specified,  no  binary  output  is  produced. 
(Save  image  is  the  assumed  output  format 
unless  the  /L  or  /R  switches  are  used.) 

is  the  optional  load  map  file. 

are  files  of  one  or  more  object  modules  to  be 
input  to  the  Linker  (these  may  be  library 
files) . 

are  switches  as  explained  in  Table  6-1  and 
Section  6.8. 

If  the  /C  switch  is  given,  subsequent  command  lines  may  be  entered  as: 
*objm,objn,. . ./sl/s2 

The  /C  switch  is  necessary  only  if  the  command  string  will  not  fit  on 
one  line  or  if  the  overlay  structure  is  used.  If  an  error  occurs  in  a 
continued  command  line  (e.g.,  7FILE  NOT  FND?) ,  only  the  line  in  error 
need  be  retyped. 


dev: 

binout 

mapout 
ob] 1 , . . . 

/s 1/s 2/s 3 
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If  an  output  file  is  not  specified,  the  Linker  assumes  that  the 
associated  output  is  not  desired.  For  example,  if  the  load  module  and 
load  map  are  not  specified,  only  error  messages  (if  any)  are  printed 
by  the  Linker. 


The  default  values  for  each  specification  are* 


Device  Filename  Extension 


Load  Module  DK: 

Map  Output  Same  as 

load  module  . 

Object  Module  DK:  or  same 
as  previous 
object  module 


none 

SAV,  REL(/R),  LDA(/L) 

none 

MAP 

none 

OBJ 

If  a  syntax  error  is  made  in  a  command  string,  an  error  message  is 
printed.  A  new  command  string  can  then  be  typed  following  the 
asterisk. 


If  a  nonexistent  file  is  specified  a  fatal  error  occurs;  control  is 
returned  to  the  command  string  interpreter,  an  asterisk  is  printed  and 
a  new  command  string  may  be  entered. 


6.2.2  Switches 

The  switches  associated  with  the  Linker  are  listed  in  Table  6-1.  The 
letter  representing  each  switch  is  always  preceded  by  the  slash 
character.  Switches  must  appear  on  the  line  indicated  if  the  command 
is  continued  on  more  than  one  line.  They  may  be  positioned  anywhere 
on  the  line.  (A  more  detailed  explanation  of  each  switch  is  provided 
in  Section  6.8.) 


Table  6-1 
Linker  Switches 


Switch 

Name 

Command 

Line 

Meaning 

/A 

1st 

Alphabetizes  the  entries  in  the  load  map. 

/B:n 

1st 

Bottom  address  of  program  is  indicated  as 
n  (illegal  for  foreground  links) . 

/c 

any 

Continues  input  specification  on  another 
command  line.  Used  also  with  /0. 

/F 

1st 

Instructs  the  Linker  to  use  the  default 
FORTRAN  library,  FORLIB.OBJ;  note  that 

FORLIB  does  not  have  to  be  specified  in 
the  command  line. 

/I 

1st 

Includes  the  global  symbols  to  be 

searched  from  the  library. 

/L 

1st 

Produces  an  output  file  in  LDA  format 
(illegal  for  foreground  links). 

(Continued  on  next  page) 
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Table  6-1  (Cont.) 
Linker  Switches 


Switch 

Name 

Command 

Line 

Meaning 

/M  or 
/Msn 

1st 

Stack  address  is  to  be  specified  at  the 
terminal  keyboard  or  via  n. 

/Osn 

any  but 
the  1st 

Indicates  that  the  program  will  be  an 
overlay  structure;  n  specifies  the 
overlay  region  to  which  the  module  is 
assigned. 

/R 

1st 

Produces  output  in  REL  format;  only 

files  in  REL  format  will  run  in  the 
foreground  (REL  format  files  may  not  be 
run  under  a  Single-Job  system) 

/s 

1st 

Allows  the  maximum  amount  of  space  in 
memory  to  be  available  for  the  Linker's 
symbol  table.  (This  switch  should  only 
be  used  when  a  particular  link  stream 
causes  a  symbol  table  overflow. ) 

/T  or 
/Tsn 

1st 

Transfer  address  is  to  be  specified  at 
terminal  keyboard  or  via  n. 

6.3  ABSOLUTE  AND  RELOCATABLE  PROGRAM  SECTIONS 

A  program  produced  by  one  of  the  RT-11  assemblers  or  FORTRAN  IV  can 
consist  of  an  absolute  program  section,  declared  by  the  .ASECT 
assembler  directive,  and  relocatable  program  sections  declared  by  the 
• CSECT  assembler  directive.  A  .CSECT  directive  is  assumed  at  the 
beginning  of  the  source  program.  The  instructions  and  data  in 
relocatable  sections  are  normally  assigned  locations  beginning  at 
1000 (octal)  or  0  for  a  foreground  link.  The  assignment  of  addresses 
can  be  influenced  by  command  string  switches  and  the  size  of  the 
absolute  section  (.ASECT,  if  present).  Each  control  section  is 
assigned  a  memory  address;  the  Linker  then  appropriately  modifies  all 
instructions  and/or  data  as  necessary  to  account  for  the  relocation  of 
the  control  sections. 


NOTE 

Foreground  programs  cannot  use  .ASECTs 
beyond  1000  (octal) ;  as  a  general 
practice,  they  should  be  avoided  under  a 
Foreground/Background  system. 

The  RT-11  Linker  handles  the  absolute  section  as  well  as  the  named  and 
unnamed  control  sections.  The  unnamed  control  section  is  internal  to 
each  object  module.  That  is,  every  object  module  can  have  an  unnamed 
control  section  but  the  Linker  treats  each  control  section 
independently.  Each  is  assigned  an  absolute  address  such  that  it 
occupies  an  exclusive  area  of  memory.  Named  control  sections,  on  the 
other  hand,  are  treated  globally;  if  different  object  modules  have 
control  sections  with  the  same  name,  they  are  all  assigned  the  same 
absolute  load  address  and  the  size  of  the  area  reserved  for  loading  of 
the  section  is  the  size  of  the  largest.  Thus,  named  control  sections 
allow  for  the  sharing  of  data  and/or  instructions  among  object 
modules.  This  is  the  same  as  the  handling  and  function  of  COMMON  in 
FORTRAN  IV.  The  names  assigned  to  control  sections  are  global  and  can 
be  referenced  as  any  other  global  symbol. 
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6.4  GLOBAL  SYMBOLS 

Global  symbols  provide  the  link,  or  communication,  between  object 
modules.  Global  symbols  are  created  with  the  . GLOBL  assembler 
directive  (see  Chapter  5) .  If  the  global  symbol  is  defined  in  an 
object  module  (as  a  label  or  by  direct  assignment) ,  it  is  called  an 
entry  symbol  and  other  object  modules  can  reference  it.  If  the  global 
symbol  is  not  defined  in  the  object  module,  it  is  an  external  symbol 
and  is  assumed  to  be  defined  (as  an  entry  symbol)  in  some  other  object 
module. 

As  the  Linker  reads  the  object  modules  it  keeps  track  of  all  global 
symbol  definitions  and  references.  It  then  modifies  the  instructions 
and/or  data  which  reference  the  global  symbols.  Undefined  globals  are 
printed  on  the  console  terminal  after  pass  1  (or  pass  2  if  a  library 
file  is  also  linked) . 


6.5  INPUT  AND  OUTPUT 

Linker  input  and  output  is  in  the  form  of  modules;  one  or  more  input 
modules  (object  files  produced  by  either  assembler  or  FORTRAN  IV)  are 
used  to  produce  a  single  output  (load)  module. 


6.5.1  Object  Modules 

Object  files,  consisting  of  one  or  more  object  modules,  are  the  input 
to  the  Linker  (the  Linker  ignores  files  which  are  not  object  modules). 
Object  modules  are  created  by  the  RT-11  assemblers  or  FORTRAN  IV.  The 
Linker  reads  each  object  module  at  least  twice  (three  times  if  library 
files  are  linked) .  During  the  first  pass  each  object  module  is  read  to 
construct  a  global  symbol  table  and  to  assign  absolute  values  to  the 
control  section  names  and  global  symbols.  If  library  files  are 
linked,  a  second  pass  is  needed  to  resolve  the  undefined  globals  from 
the  library  files  and  force  their  associated  object  modules  into  the 
root;  on  the  final  pass,  the  Linker  reads  the  object  modules,  links 
and  relocates  the  modules  and  outputs  the  load  module. 


6.5.2  Load  Module 


The  primary  output  of  the  Linker  is  a  load  module  which  may  be  loaded 
and  run  under  RT-11.  The  load  module  is  output  as  a  save  image  file 
(SAV)  for  use  under  a  Single-Job  system  or  the  background  job.  Under 
an  F/B  System,  the  /R  switch  must  be  used  to  produce  a  REL 
(reloctable)  format  foreground  load  module  if  the  job  is  to  run  in  the 
foreground.  An  absolute  load  module  (LDA)  is  produced  if  the  module 
is  to  be  loaded  by  the  Absolute  Loader. 


The  load  module  for  a  save  image  file  is  arranged  as  follows : 


Root  Segment 


Overlay 

Segments 

(optional) 


For  a  REL  image  file,  the  load  modules  are  arranged  as: 
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Root  Segment 

Overlay 

Resident 

Overlay 

Segments 

REL 

REL  Blocks 

(optional) 

Blocks 

(optional) 

The  first  256-word  block  of  the  root  segment  (main  program)  contains 
the  memory  usage  map  and  the  locations  used  by  the  Linker  to  pass 
program  control  parameters.  The  memory  usage  map  outlines  the  blocks 
of  memory  used  by  the  load  module  and  is  located  in  locations  360  to 
377. 


The  control  parameters  cure  located  in  locations  40-50  and  contain  the 
following  information  when  the  module  is  loaded: 


Address 


Information 


40:  Start  Address  of  program 

42:  Initial  setting  of  R6  (stack  pointer) 

44:  Job  Status  Word 

46:  USR  Swap  Address  (0  implies  normal  location) 

50:  Highest  Memory  Address  in  user's  program 


For  a  foreground  link  the  following  additional  parameters  contain 
information : 


34,36:  TRAP  Vector 

52:  Size  of  Resident  (words) 

54:  Sum  of  the  Resident  and  largest  Overlay  Region 

(words) 

56:  F/B  Identification 

60 :  Address  of  Resident  REL  Block 


Memory  locations  0-476  (comprising  the  interrupt  vectors  and  system 
communication  area)  may  be  assigned  initial  values  by  using  an  .ASECT 
assembler  statement  and  will  appear  in  block  0  of  the  load  module,  but 
there  are  restrictions  on  the  use  of  .ASECTs  in  this  region.  The 
Linker  does  not  permit  an  .ASECT  of  location  54  or  of  locations 
360-377  (the  memory  usage  map  is  passed  in  those  locations) .  In 
addition,  for  foreground  links,  am  .ASECT  of  words  52-60  is  not 
permitted  (additional  parameters  are  passed  to  FRUN  in  those 
locations ) . 

Any  location  which  is  not  restricted  may  be  set  with  an  .ASECT,  but 
caution  should  be  used  in  changing  the  system  communication  area. 
Restricted  areas,  such  as  the  region  360-377,  must  be  initialized  by 
the  program  itself.  There  are  no  restrictions  on  .ASECTs  if  the 
output  format  is  LOA. 

Locations  in  the  region  0-476  which  are  initialized  by  an  .ASECT  in  a 
program  may  never  be  loaded  when  the  program  is  executed.  There  are 
two  reasons  for  this.  For  background  tasks  (or  the  Single-Job  system) 
the  R,  RUN,  and  GET  commands  will  not  load  an  address  protected  by  the 
monitor's  memory  protection  map.  The  addresses  normally  protected 
include  such  important  areas  as  the  system  device  and  console  device 
vectors,  but  protection  may  be  extended  dynamically  (e.g.,  by  a 
foreground  task  issuing  a  .PROTECT  call).  For  foreground  tasks,  the 
FRUN  command  will  load  only  locations  34-50  (34  is  the  TRAP 
instruction  vector)  and  all  other  .ASECTs  are  ignored.  The  procedure 
for  loading  these  locations  is  to  do  so  at  run-time  using  MOV 
instructions . 
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6.5.3  Load  Map 

If  requested,  a  load  map  is  produced  following  the  completion  of  the 
initial  pass(es)  of  the  Linker.  This  map,  shown  in  Figure  6-1, 
diagrams  the  layout  of  memory  for  the  load  module. 

Each  .CSECT  included  in  the  linking  process  is  listed  in  the  load  map. 
The  entry  for  a  .CSECT  includes  the  name  and  low  address  of  the  section 
and  its  size  (in  bytes).  The  remaining  columns  contain  the  entry 
points  (or  globals)  found  in  the  section  and  their  addresses. 

The  map  begins  with  the  name  of  the  load  module  and  the  date  of 
creation.  The  modules  located  in  the  root  segment  of  the  load  module 
are  listed  next,  followed  by  those  modules  which  were  assigned  to 
overlays  in  order  by  their  region  number  (see  Section  6.6).  Any 
undefined  global  symbols  are  then  listed.  The  map  ends  with  the 
transfer  address  (start  address)  and  high  limit  of  relocatable  code. 


NOTE 

The  load  map  will  not  reflect  the 
absolute  addresses  for  a  REL  file 
created  to  be  run  as  a  foreground  job; 
the  base  relocation  address  specified  at 
FRUN  time  must  be  added  to  obtain  the 
absolute  addresses. 

For  example,  assume  the  FRUN  command  is  used  to  run  the  program 
RELTSTs 

.FRUN  RELTST/P 
LOADED  AT  137150 

When  linked,  the  following  load  map  is  produced: 


RT-tl  LINK 

X03»16 

LOAO  MAP 

RELTST. 

REL 

03-SEP- 

74 

SECTION 

AOOR 

SIZE 

ENTRV 

AOOR 

ENTRY 

AOOR 

ENTRY 

AOOR 

.  ABS. 

000000 

000350 

STKSIZ 

000012 

SPVEC 

000320 

SCRPOS 

001750 

TSTVT1 

0003S0 

000326 

8GTB 

0006Tb 

001116 

SDSINT 

000676 

8ST0PF 

000710 

SNR 

000752 

STACKP 

000764 

STATBF 

001106 

SOPC 

001142 

SL1NKF 

001146 

SLCOIS 

001150 

SLCNT 

001152 

SD8VEC 

001154 

STACKE 

001202 

SOFILE 

001226 

SYS 

001244 

SBLANK 

001246 

SLINK 

001252 

S6YPAS 

001256 

SCTRAK 

001260 

SLSRA 

001276 

SCUSER 

001302 

SNULL 

001316 

SXT 

001326 

SYT 

001330 

SLPINT 

001404 

SLPBUF 

001434 

8NR6UF 

001446 

STRAKC 

001562 

SX3T0R 

001572 

SYSTOR 

001574 

SSOINT 

001670 

SV8TIN 

001676 

SVSTP 

001722 

SP0V1 

001756 

SPEXIT 

001764 
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OVERLAY 

REGION 

000001 

SEGMENT 

000001 

SGTl 

002016 

000210 

SVINIT 

002016 

SVNSRT 

002130 

SGT2 

002226 

000102 

SVBLNK 

002226 

SGT3 

002330 

000130 

SVTRAK 

002330 

SN0SYN 

002430 

OVERLAY 

REGION 

000001 

SEGMENT 

000002 

SGT4 

002016 

000602 

SVRTLK 

002016 

SVSCRL 

002512 

TRANSFER  ADDRESS  •  000350 
HIGH  LIMIT  •  002620 


SVFDEL 

002100 

SV0TOP 

002114 

SVRM0V 

002174 

SV8TRT 

002214 

SVRSTR 

002256 

SVSRCH 

002300 

SVLPEN 

002410 

SVSTPM 

002420 

SSYNC 

002440 

SNAME 

002450 

9VUNLK 

002300 

SVLSET 

002404 

To  determine  the  address  of  TSTVT1,  137150  must  be 
thus  137520  is  the  absolute  address  of  TSTVT1.  The 
is  137150  plus  350,  or  137520. 


added  to  000350; 
transfer  address 


6.5.4  Library  Files 

The  RT-11  Linker  has  the  capability  of  automatically  searching 
libraries.  Libraries  are  composed  of  library  files— specially 
formatted  files  produced  by  the  Librarian  program  (Chapter  7)  which 
contain  one  or  more  object  modules.  The  object  modules  provide 
routines  and  functions  to  aid  the  user  in  meeting  specific  programming 
needs.  (For  example,  FORTRAN  has  a  special  library  containing  all 
necessary  computational  functions — TAN,  ATAN,  etc.)  By  using  the 
Librarian,  libraries  can  be  created  and  updated  so  that  routines  which 
are  used  more  than  once,  or  routines  which  are  used  by  more  than  one 
program,  may  be  easily  accessed.  Selected  modules  from  the 
appropriate  library  file  are  linked  as  needed  with  the  user  program  to 
produce  one  load  module.  Libraries  are  further  described  in  Section 
6.7  and  in  Chapter  7. 


NOTE 

Library  files  that  have  been  combined 
under  PIP  are  illegal  as  input  to  both 
the  Linker  and  the  Librarian. 
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RT-U  LINK  V03-01  LOAD  MAP 
SORT  . 5 A  V  19-SEP-74 


SECTION  ADDR 

,  ASS,  000000 

001000 

001220 

002604 


005104 

005264 


005366 

005406 

005454 

005536 

005574 

005770 

006016 


006062 
006154 
SERHTB  006156 
SERRS  006256 
011116 
012652 
013054 
013472 
013600 
014102 
014364 
014472 
015366 
015476 
016112 


SIZE 

ENTRY 

001000 

SUSRS* 

5LRECL 

000220 

001364 

SOTI 

002300 

OCXS 

RCIS 

GCOS 

DCOS 

000160 

ISMS 

5LSNTR 

000102 

MOISSS 
HOI SS A 
RELS 

MO  I  SMS 
MQIS0S 
HOI S 1 S 

000020 

IFRS 

000046 

EOLS 

000062 

TVLS 

TVQS 

000036 

CAIS 

000174 

SORT 

000026 

MOFSRS 

MOFSRP 

000044 

NMIS1M 

BEOS 

BRAS 

000072 

FOOS 

000002 

SAOTS 

0001 00 

002637 

001534 

SFIO 

000202 

SFMTDR 

000416 

SCLOSE 

000106 

LCIS 

000302 

SGETRE 

000262 

SPUTRE 

000106 

SFCHNL 

000674 

SOPEN 

000110 

SCiUMPL 

000414 

SPUTBL 

000042 

SWA  IT 

ADDR 

ENTRY 

000000 

SV005A 

000210 

STRACE 

001246 

002604 

ICIS 

003006 

OCOS 

004144 

FCOS 

004164 

005104 

SISNTR 

005130 

005264 

MQLSSS 

005274 

MQISXS 

005300 

MOISIM 

005314 

MQ I $MM 

005330 

MOIS0M 

005344 

MOISIM 

005366 

IFWS 

005406 

005454 

TVFS 

005476 

TVP$ 

005536 

CALS 

005574 

005770 

MOFSRM 

006012 

006016 

NMIS1I 

006036 

BGTS 

006050 

BNES 

006062 

EXIT 

006154 

011600 

012652 

013054 

SFMTDW 

013472 

LCOS 

013600 

014102 

014364 

014472 

015366 

STTYIN 

015476 

016112 

SGETBL 

ADDR 

ENTRY 

000001 

snlchn 

004737 

002612 

SGET 

003712 

ICOS 

004152 

ECOS 

005110 

LSNS 

005264 

MOISSM 

005300 

MQLSIS 

005304 

MQISI A 

005320 

MOISMA 

005334 

MOIS0A 

005352 

005400 

M0IS1A 

005462 

T  VOS 

005504 

005544 

TVIS 

005776 

MOFSRA 

006026 

BLES 

006044 

BGES 

006054 

blts 

006074 

STPS 

012702 

SINITI 

013540 

013722 

015676 

SEOFIL 

TRANSFER  ADDRESS  ■  001000 
HIGH  LIMIT  >  016154 


Figure  6-1 

Linker  Load  Map  for  Background  Job 


ADDR 

000006 


002772 

003720 

004156 

005124 

005270 

005300 

005310 

005324 

005340 

005360 


005470 

005512 


006006 

006034 

006046 

006056 

006074 


012750 


016046 
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6.6  USING  OVERLAYS 

The  RT-11  program  overlay  facility  enables  the  user  to  have  virtually 
unlimited  memory  space  for  an  assembly  language  or  FORTRAN  program.  A 
program  using  the  overlay  facility  can  be  much  larger  them  would 
normally  fit  in  the  available  memory  space,  since  portions  of  the 
program  (called  overlay  segments)  reside  on  a  backup  storage  device 
(disk  or  OECtape) • 

The  RT-11  overlay  scheme  is  a  strict  multi-region  arrangement;  it  is 
not  tree-structured.  Figure  6-2  diagrams  this  scheme.  The  overlay 
system  which  the  user  constructs  from  his  completed  program  is 
composed  of  a  root  segment,  memory-resident  overlay  regions,  and  the 
overlay  segments  stored  on  the  backup  storage  device.  The  root 
segment  is  a  required  part  of  every  overlay  program  and  contains  all 
transfer  addresses;  it  must  therefore  never  be  overlaid.  An  overlay 
region  corresponds  to  a  run-time  area  of  memory  that  is  shared  by  two 
or  more  subroutines  (called  co-resident  subroutines);  there  is  a 
distinct  memory  area  for  each  overlay  region.  Overlay  segments  are 
portions  of  the  save  image  or  REL  format  file  from  which  the  user's 
program  is  run;  these  are  brought  into  memory  as  needed. 


A5*  A/C 

=  Root 

B/Osl/C 

=  Segment 

i  \ 

1  ■  Region  1 

C/O s 1/C 

=  Segment 

2  J 

D/O: 2/C 

=*  Segment 

3 

>  =  Region  2 

E/0: 2 

=  Segment 

4  J 

Figure  6-2 
Overlay  Scheme 


Overlay  regions  are  specified  to  the  Linker  via  the  /0  switch  as 
described  in  Section  6.8.8.  The  size  of  the  overlay  region  is 
calculated  by  the  Linker  to  be  the  size  of  the  largest  group  of 
subroutines  that  can  occupy  the  region  at  one  time.  The  Linker 
creates  the  overlay  regions  and  edits  the  program  to  produce  the 
desired  overlays  at  run-time. 

Figure  6-3  shows  a  diagram  of  memory  for  a  program  which  has  an 
overlay  structure  and  Figure  6-4  is  a  listing  of  the  run-time  overlay 
handler. 


6-10 


Linker 


ADDRESS 

0 

400 


SYSTEM  AREA 


OVERLAY  HANDLER 
(INCLUDED  B^UNKER) 


ROOT  SEGMENT 
OF  PROGRAM 
(BASICR.FPMP) 


IDENTIFICATION  WORD 


1 

OVERLAY 

[ 

REGION  1 

(BASICX) 

(BASIC  E) 

IDENTIFICATION  WORD 


OVERLAY  REGION  2 
(BASICH) 


MONITOR 


Figure  6-3 

Memory  Diagram  Showing  BASIC  Link  With  Overlay  Regions 


.SSTTl  the  run»time  overlay  HANDLER 
THE  FOLLOWING  CODE  13  INCLUOED  IN  THE  USER'S  PROGRAM  BY  THE 

linker  whenever  overlays  are  requested  by  the  user. 

56.8  MICROSECONDS  (aPPRQXJ  IS  ADOED  TO  EACH  REFERENCE  OF 
A  RESIDENT  OVERLAY  SEGMENT, 

THE  RUN-TIME  OVERLAY  HANDLER  IS  CALLEO  BY  A  DUMMY 
SUBROUTINE  OF  The  following  FORMI 

JSR  R5.S0VRH  ICALL  TO  COMMON  CODE 

.WORD  ^OVERLAY  Np  IN  OF  DESIRED  SEGMENT 

.WORO  «ENTRY  ADDR>  I  ACTUAL  CORE  ADOR 

one  dummy  routine  of  the  above  form  is  stored  in  the  resident 

PORTION  Op  THfe  USER'S  PROGRAM  FOR  EACH  ENTRY  POINT  TO 
AN  OVERLAY  SEGMENT,  ALL  REFERENCES  TO  THE  ENTRY  POINT  ARE 
MODIFIED  BY  The  linker  TO  INSTEAO  be  REFERENCES  TO  THE  APPRO¬ 
PRIATE  DUMMY  ROUTINE.  EACH  OVERLAY  SEGMENT  IS  CALLED  INTO 
CORE  AS  A  UNIT  aNO  MUST  BE  CONTIGUOUS  IN  CURE,  AN  OVERLAY 
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I  Sf-OMENT  MaY  HAVt  ANY  NUMBER  OF  ENTRY  POINTS,  TO  THE  LIMITS 
\  OF  CORE  MEMORY.  ONLY  ONE  SEGMENT  AT  A  TIME  MAY  OCCUPY  AN 
I  overlay  region, 

f  RESTRICTIONS! 

I  SINCE  REFERENCES  TO  OVERLAY  SEGMENTS  ARE  AUTOMATICALLY  TRANS- 
I  LATEO  BY  THE  LINKER  INTO  REFERENCES  TO  DUMMY  SUBROUTINES, 

»  THE  PROGRAMMER  MUST  NOT  ATTEMPT  TO  REFERENCE  OATA  IN  AN  OVER- 

|  lay  by  using  global  symbols. 


SOVTAB* 100B*SOVRHE-SOVRH 

SOVRHJ 

MU  V 

R0,-(SP) 

MOV 

R1,-(SP) 

MOV 

R2,-CSPJ 

SOyRMBI 

> 

MOV 

(R8J ♦ , RB 

>PICK  UP  OVERLAY  number 

BR 

SFiRST 

1  FIRST  CALL  ONLY  *  *  * 

MOV 

RI0,R1 

SOVRHAI 

ADO 

•  $OV  T  AB»6 , R 1 

fCALC  TABLE  ADOR 

MOV 

(Rl)+,R2 

1  GET  CORE  ADOR  OF  OVERLAY  KEGlOi 

CMP 

R0 » #R2 

>IS  OVERLAY  ALREAOY  RESIDENT? 

BEQ 

SENTER 

! YES,  BRANCH  TO  IT 

.REAOr 

17, R2, (R l) ♦» (R1 )  ♦  f READ  FROM  OVERLAY  FILE 

BCS 

SERR 

SEnTEr! 

MOV 

(SP)*,R2 

fRESTORE  USER'S  REGS 

MOV 

(SH) +,Rt 

MOV 

(5P) ♦ , R0 

MOV 

#R8, R3 

1  GET  ENTRY  ADDRESS 

RTS  • 

RB 

i enter  overlay  routine  and 

»RESTQRt  USER'S  R5 

SFIRSTI 

MOV 

•125B0, SUVRHB 

| RESTORE  SWITCH  INSTR 

MOV 

CPC} ♦ » R 1 

f  ST  ART  AOOR  FOR  CLEAR  OPERATION 

SHROOTI 

•  N0R9 

0 

| HIGH  AOOR  OF  ROOT  SEGMENT 

MOV 

£PC)*,R2 

J  COUNT 

SHQVLYI 

,R0RD 

0 

! HIGH  LIMIT  OF  OVERLAYS 

IS! 

CLR 

(Rl )  + 

iclear  all  overlay  regions 

CMP 

R 1 ,  R2 

BLO 

1$ 

BR 

SOVRHB 

f AND  RETURN  TO  CALL  IN  PROGRESS 

SERR* 

EMT 

37® 

I  generate  always  fatal  error 

.BYTE 

0,373 

t AND  DISREGARD  SOFT  ERROR 

SO VRH£ 1 

i  overlay  segment  table  fqllowsi 

I  SOVTAB!  .word  «core  ADDR>,<RElATIvE  BLK»,<roRO  count> 

i  three  ruros  per  entry,  one  entry  per  overlay  segment. 

I  ALSO,  THERE  IS  one  roro  prefixed  to  each  overlay  region 
»  That  identifies  The  segment  currently  resident  in  that  region, 
I  THIS  nord  is  an  index  into  the  sovtab  table. 


Figure  6-4 

The  Run-Time  Overlay  Handler 
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There  is  no  special  code  or  function  call  needed  to  use  overlays  but 
the  following  rules  must  be  observed  when  referencing  parts  of  the 
user  program  which  might  be  overlaid. 

1.  Calls  or  branches  to  overlay  segments  must  be  made  directly 
to  entry  points  in  the  segment.  Entry  points  are  locations 
tagged  with  a  global  symbol  (refer  to  Chapter  5f  Section 
5.5.10).  For  example/  if  ENTER  is  a  global  tag  in  an  overlay 
segment : 

JMP  ENTER  is  legal/  but 

JMP  ENTER+6  is  illegal. 

2.  Entries  in  overlay  segments  can  be  used  only  for  transfer  of 
control  and  not  for  referencing  data  within  an  overlay 
section  (e.g.#  MOV  ENTER/ R4  is  illegal  if  ENTER  is  in  an 
overlay  segment/  but  MOV  #ENTER#R7  is  legal  because  it  is 
used  for  transfer  of  control).  A  violation  of  this  rule 
cannot  be  detected  by  the  assembler  or  Linker  so  no  error  is 
issued;  however/  it  can  cause  the  program  to  use  incorrect 
data. 

3.  When  calls  are  made  to  overlays/  the  entire  return  path  must 
be  in  memory.  This  will  happen  if  these  rules  are  followed: 

Calls  (with  expected  return)  may  be  made  from  an  overlay 
segment  only  to  entries  in  the  same  segment/  the  root 
segment/  or  an  overlay  segment  with  a  greater  region 
number. 

Calls  to  entries  in  the  same  region  as  the  call  must  be 
entirely  within  the  same  segment/  not  another  segment  in 
the  same  region. 

Jumps  (with  no  expected  return)  can  be  made  from  an 
overlay  segment  to  any  entry  in  the  program.  However/ 
jumps  should  not  reference  an  overlay  region  whose  number 
is  lower  than  the  region  from  which  the  last  unreturned 
call  was  made  (e.g.#  if  a  call  was  made  from  region  3/ 
then  no  jumps  should  reference  regions  1,  2  or  3  until 
the  call  has  returned) . 

Subroutines  in  the  root  segment  may  be  called  from 
overlay  segments;  in  turn,  they  may  call  entries  from 
the  same  overlay  segment  which  called  them/  or  from  the 
root  segment/  or  from  another  overlay  segment  with  a 
greater  region  number.  Such  subroutines  are  considered 
part  of  the  overlay  segment  which  called  them. 

4.  A  • CSECT  name  cannot  be  used  to  pass  control  to  an  overlay. 
It  will  not  cause  the  appropriate  segment  to  be  loaded  into 
memory  (e.g.#  JSR  PC/OVSEC  is  illegal  if  OVSEC  is  used  as  a 
.CSECT  name  in  an  overlay).  As  stated  in  1  above ,  a  global 
symbol  must  be  used  to  pass  control  from  one  segment  to  the 
next. 

5.  Channel . 17 (octal)  cannot  be  used  by  the  user  program  because 
overlays  are  read  on  that  channel. 

6.  Object  modules  acquired  from  a  library  file  cannot  be  placed 
into  overlays. 
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7.  Library  files  may  not  be  specified  on  the!  same  command  line 
as  an  overlay. 

8.  Overlay  regions  must  be  specified  in  ascending  order  and  are 
read-only.  Unlike  USR  swapping,  an  overlay  segment  does  not 
save  the  segment  it  is  overlaying.  Any  tables,  variables,  or 
instructions  that  are  modified  within  a  given  overlay  segment 
are  re-initialized  to  their  original  values  in  the  SAV  or  REL 
file  if  that  segment  has  been  overlaid  by  another  segment. 
Any  variables  or  tables  whose  values  must  be  maintained 
across  overlays  should  be  placed  in  the  root  segment. 

9.  .ASECTs  of  any  size  in  an  overlay  foreground  link  are 
illegal;  the  error  message  ?ILL  ASECT?  is  printed  and  the 
line  is  aborted. 

The  following  information  should  be  noted  when  writing  FORTRAN 
overlays . 

1.  When  dividing  a  FORTRAN  program  into  a  root  segment  and 
overlay  regions  (and  subsequently  dividing  each  overlay 
region  into  overlay  segments) ,  routine  placement  should  be 
carefully  considered.  The  user  should  always  remember  that 
it  is  illegal  to  call  a  routine  located  in  a  different 
overlay  segment  in  the  same  overlay  region,  or  an  overlay 
region  with  a  lower  numeric  value  (as  specified  by  the  Linker 
overlay  switch,  /0:n)  from  the  calling  routine.  The  user 
should  divide  each  overlay  region  into  overlay  segments  which 
never  need  to  be  resident  simultaneously  (i.e.,  if  segments  A 
and  B  are  assigned  to  region  X,  they  cannot  call  each  other 
because  they  occupy  the  same  locations  in  memory) . 

2.  The  FORTRAN  main  program  unit  must  be  placed  in  the  root 
segment. 

3.  In  an  overlay  environment,  subroutine  calls  and  function 
subprogram  references  may  refer  only  to  one  of  the  following: 

A  FORTRAN  library  routine  (e.g.,  ASSIGN,  DCOS) 

A  FORTRAN  or  assembly  language  routine  contained  in  the 
root  segment 

A  FORTRAN  or  assembly  language  routine  contained  in  the 
same  overlay  segment  as  the  calling  routine 

A  FORTRAN  or  assembly  language  routine  contained  in  a 
segment  whose  region  number  is  greater  them  that  of  the 
calling  routine 

4.  In  an  overlay  environment,  COMMON  blocks  must  be  placed  so 
that  they  are  resident  when  referenced.  Blank  COMMON  is 
always  resident  since  it  is  always  placed  in  the  root 
segment.  All  named  COMMON  must  be  placed  either  in  the  root 
segment,  or  into  the  segment  whose  region  number  is  lowest  of 
all  segments  which  reference  the  COMMON  block.  A  named 
COMMON  block  cannot  be  referenced  by  two  segments  in  the  same 
region  unless  the  COMMON  block  appears  in  a  segment  of  a 
lower  region  number.  The  Linker  automatically  places  a 
COMMON  block  into  the  root  segment  if  it  is  referenced  by  the 
FORTRAN  main  program  or  by  a  subprogram  that  is  located  in 
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the  root  segment.  Otherwise  the  Linker  places  a  COMMON  block 
in  the  first  segment  encountered  in  the  Linker  command  string 
that  references  that  COMMON  block. 

5.  All  COMMON  blocks  which  are  initialized  (by  use  of  DATA 
statements)  must  be  so  initialized  in  the  segment  in  which 
they  are  placed. 

Refer  to  the  RT-11  FORTRAN  COMPILER  AND  OBJECT  TIME  SYSTEM  USER'S 
MANUAL  (DEC-ll-LRFPA-A-D)  for  more  details. 

The  .ASECT  never  takes  part  in  overlaying  in  any  way  (i.e.,  if  part  of 
an  .ASECT  is  destroyed  by  overlay  operations ,  it  is  not  restored  by 
the  overlay  handler) . 

The  aforementioned  sets  of  rules  apply  only  to  communications  among 
the  various  modules  that  make  up  a  program.  Internally,  each  module 
must  only  observe  standard  programming  rules  for  the  PDP-11  (as 
described  in  the  PDP-11  PROCESSOR  HANDBOOK  and  in  Chapter  5) . 

It  should  be  noted  that  the  condition  codes  set  by  a  user  program  are 
not  preserved  across  overlay  segment  boundaries. 

The  Linker  provides  overlay  services  by  including  a  small  resident 
overlay  handler  (Figure  6-4)  in  the  same  file  with  the  user  program  to 
be  used  at  program  run-time.  This  overlay  handler  plus  some  tables 
are  inserted  into  the  user's  program  beginning  at  the  bottom  address 
computed  by  the  Linker.  The  Linker  moves  the  user's  program  up  in 
memory  by  an  appropriate  amount  to  make  room  for  the  overlay  handler 
and  tables,  if  necessary. 


6.7  USING  LIBRARIES 

Libraries  are  specified  in  a  command  string  in  the  same  fashion  as 
normal  modules;  they  may  be  included  anywhere  in  the  command  string, 
with  the  exception  of  overlay  lines.  If  a  global  symbol  is  undefined 
at  the  time  the  library  is  encountered  in  the  input  stream  and  a 
module  is  included  in  the  library  which  includes  that  global 
definition,  that  module  is  pulled  from  the  library  and  linked  into  the 
load  image.  Only  the  modules  needed  to  resolve  references  are  pulled 
from  the  library;  unused  modules  are  not  linked. 

NOTE 

Modules  in  one  library  may  call  modules 
from  another  library;  however,  the 
libraries  must  appear  in  the  command 
string  in  the  order  in  which  they  are 
called.  For  example,  assume  module  X  in 
library  ALIB  calls  SQRT  from  the  FORTRAN 
library.  To  correctly  resolve  all 
globals,  the  order  of  ALIB  and  the 
FORTRAN  library  should  appear  in  the 
command  line  as; 

*Z«B»ALIB/F 
or  AL IB  >  FORI... IB 
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Module  B  is  the  root.  It  calls  X  from 
ALIB  and  brings  X  into  the  root.  X  in 
turn  calls  SQRT  which  is  brought  from 
FORLIB  into  the  root. 


FORTRAN  libraries  cannot  precede  their  root  segment  in  a  command  line 
as  this  creates  a  bad  transfer  address.  For  example: 

*X=ROOT/F 
*X=ROOTr FORLIB 

are  legal,  but: 


#X=FORL IB  f ROOT 

is  not.  Unpredictable  results  will  occur. 


6.7.1  User  Library  Searches 

Object  modules  from  the  named  user  libraries  built  by  the  Librarian 
are  relocated  selectively  and  linked  by  the  Linker.  The  RT-11  Linker 
searches  a  specified  library  file  during  the  library  pass  as  follows 
(refer  to  Figure  6-5  for  a  flowchart  representation  of  this  process) : 

1.  If  there  are  any  undefined  globals  in  the  Linker's  table 
when  a  library  is  encountered  in  the  command  string,  proceed 
to  step  2;  otherwise  skip  this  library  (go  to  step  5) . 

2.  Read  the  library  directory. 

3.  If  any  of  the  undefined  globals  can  be  defined  by  a  module 
in  this  library,  include  the  relevant  module  into  the  linked 
output  file;  otherwise,  go  to  step  5. 

4.  If  any  undefined  globals  remain  in  the  Linker's  table  and 
they  have  not  been  looked  for  in  the  library,  return  to  step 
2;  otherwise  go  to  step  5. 

5.  Close  the  library  file. 

6.  Go  to  the  next  element  in  the  command  string. 

This  search  method  allows  modules  to  appear  in  any  order  in  the 
library.  Any  number  of  libraries  may  be  specified  in  a  link,  and  they 
may  be  positioned  anywhere,  with  the  exception  of  overlay  segments  and 
the  restrictions  noted  in  Section  6.7. 
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PROCESS  FILE 


READ 

LIBRARY  DIRECTORY 

_ s 

1 . . 

SEARCH 

UNDEFINED  GLOBALS 
FROM  LIBRARY 

Figure  6-5 
Library  Searches 


NOTE 

For  faster  Linker  performance ,  the  user 
should  specify  all  object  files  before 
library  files 9  and  all  user  library 
files  before  the  system  library  files. 
For  example: 
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#A»A>BrUSELIB/F 

where  A  and  B  are  object  modules ,  USELIB 
is  a  user-created  library  file,  and  /F 
denotes  the  default  FORTRAN  library, 

FORLIB. 

Libraries  are  input  to  the  Linker  as  any  other  input  file.  Assume  the 
following  command  string  to  the  Linker: 

*  TASKO 1 .  SAM  *  LP  J  -:MA  I N  ♦  OBJ  r  MEASUR .  OBJ 

This  causes  program  MAIN. OBJ  to  be  read  from  DK:  as  the  first  input 
file.  Any  undefined  symbols  generated  by  program  MAIN. OBJ  should  be 
satisfied  by  the  library  file  MEASUR.OBJ  specified  in  the  second  input 
file.  The  load  module,  TASK01.SAV  is  put  on  DK:  and  a  load  map  goes 
to  the  line  printer. 


6 . 8  SWITCH  DESCRIPTION 

The  switches  summarized  in  Table  6-1  are  described  in  detail  below. 


6.8.1  Alphabetize  Switch 

The  /A  switch  requests  the  Linker  to  list  linked  modules  in 
alphabetical  order  as  follows:  .CSECTs,  module  names,  and  entry 
points  within  modules.  The  load  map  is  normally  arranged  in  order  by 
module  address  as  shown  in  Figure  6-1.  Figure  6-6  is  an  example  of  an 
alphabetized  load  map  for  a  background  job. 


6.8.2  Bottom  Address  Switch 

The  /B  switch  specifies  the  lowest  address  to  be  used  by  the 
relocatable  code  in  the  load  module.  When  /B  is  not  specified,  the 
Linker  positions  the  load  module  so  that  the  lowest  address  is 
location  1000  (octal) ,  or  0  for  a  foreground  link.  If  the  .ASECT 
length  is  greater  than  1000,  the  length  of  .ASECT  is  used. 

The  form  of  the  bottom  switch  is: 

/B:n 

n  is  a  six-digit  unsigned  octal  number  which  defines  the  bottom 
address  of  the  program  being  linked.  An  error  message  results  if  n  is 
not  specified  as  part  of  the  /B  command. 

If  more  than  one  /B  switch  is  specified  during  the  creation  of  a  load 
module,  the  first  /B  switch  specification  is  used. 


NOTE 

The  bottom  value  must  be  an  unsigned 
even  octal  number.  If  the  value  is  odd, 
an  error  message  is  generated. 
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RT»il  LINK  V03-01  LOAD  MAP 
SORT  • S A  V  19-SEP-74 


SECTION  ADOR 

SIZE 

ENTRY 

AODR 

ENTRY 

ADDR 

EN7RY 

AODR 

,  ASS,  000000 

0&100U 

SLRECL 

000210 

SNLCHN 

000006 

SUSRStf 

000000 

STRACE 

004737 

SV005A 

00000  1 

001000 

0002216 

001220 

001364 

SOTI 

001246 

002604 

002300 

OCOS 

004164 

ECOS 

004156 

FCOS 

004152 

GCOS 

004144 

ICIS 

002612 

ICOS 

003720 

OCIS 

002604 

OCOS 

003712 

RC  IS 

003006 

SGET 

002772 

005104 

000160 

ISNS 

005104 

LSNS 

005124 

SISNTN 

005110 

SLSNTH 

0N5130 

005264 

000102 

MQISIA 

005310 

MOISIM 

005304 

MOISIS 

005300 

MOISMA 

005324 

MOISMM 

005320 

MOISMS 

005314 

MOISSA 

005274 

MOISSM 

005270 

MOISSS 

005264 

MOIS0A 

005340 

MOIS0M 

005334 

MOIS0S 

005330 

M0IS1A 

005360 

MOISIM 

005352 

MOISIS 

005344 

MOLSIS 

005300 

MOLSSS 

005264 

RELS 

005300 

005366 

000020 

IFRS 

005366 

IFW$ 

005400 

005406 

000046 

fcOLS 

005406 

005454 

000062 

TVDS 

005470 

T  VPS 

005462 

TV  IS 

005512 

TVLS 

005454 

T  VPS 

005504 

T  VOS 

005476 

005536 

000036 

C  A  I S 

005536 

CALS 

005544 

005574 

000174 

SORT 

005574 

005770 

000026 

mofsra 

006006 

MOFSRM 

005776 

MOPSRP 

006012 

MOFSRS 

005770 

006016 

000044 

BEOS 

006036 

BGES 

006046 

BGTS 

006044 

bles 

006034 

BLTS 

006056 

bnes 

006054 

BRAS 

006050 

NMIS1I 

006026 

NMIS1M 

006016 

006062 

000072 

EXIT 

006074 

POOS 

006062 

STPS 

006074 

006154 

000002 

SAOTS 

006154 

SERRTB  006156 

000100 

SERR3  006256 

002637 

011116 

001534 

SFIO 

011600 

012652 

000202 

sfmtdr 

012652 

SFMTDN 

012702 

SINITI 

012750 

013054 

000416 

SCIOSE 

013054 

013472 

000106 

LCIS 

013472 

LCOS 

013540 

013600 

000302 

SGETRE 

013600 

STTYIN 

013722 

014102 

000262 

SPUTRE 

014102 

014364 

000106 

SFCHNL 

014364 

014472 

000674 

SOPEN 

014472 

015366 

000110 

SOUMPL 

015366 

015476 

000414 

SEOFIL 

016046 

SGET6L 

015676 

sputbl 

015476 

016112 

000042 

SWAIT 

016112 

TRANSFER  ADDRESS  ■  001000 
HIGH  LIMIT  »  01615a 

Figure  6-6 

Alphabetized  Load  Map  for  a  Background  Job 
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/B  is  illegal  with  foreground  links.  (0  is  assumed.) 
Example : 


^OUTPUT » LP  5  * INPUT/B i 500 


Causes  the  input  file  to  be 
linked  starting  at  location 
500  (octal). 


6.8.3  Continue  Swi tch 


The  Continue  switch  (/C)  is  used  to  allow  additional  lines  of  command 
string  input.  The  /C  switch  is  typed  at  the  end  of  the  current  line 
and  may  be  repeated  on  subsequent  command  lines  as  often  as  necessary 
to  specify  all  input  modules  for  which  memory  is  available.  If  memory 
is  exceeded,  an  error  message  is  output.  A  /C  switch  is  not  entered 
on  the  last  line  of  input. 


Example : 


*  OUTPUT f LP : r INPUT/C 

* 


Input  is  to  be  continued  on 
the  next  line;  the  Linker 
prints  an  asterisk. 


6.8.4  Default  FORTRAN  Library  Switch 

By  indicating  the  /F  switch  in  the  command  line,  the  FORTRAN  library, 
FORLIB.OBJ  on  the  default  device  (SY:),  is  linked  with  the  other 
object  modules  specified;  the  user  does  not  need  to  specify  FORLIB. 
For  example: 

*FILEfLPi=AB.0BJ/F 

The  object  module  AB.OBJ  and  the  FORTRAN  library  FORLIB  are  linked 
together  to  form  a  load  module  called  FILE.SAV.  (Note  that  the  FORLIB 
default  is  SY: FORLIB. OBJ,  not  DK : FORLIB. OBJ. ) 

6.8.5  Include  Switch 

The  /I  switch  allows  subsequent  entry  at  the  keyboard  of  global 
symbols  to  be  taken  from  any  library  and  included  in  the  linking 
process.  When  the  /I  switch  is  specified,  the  Linker  prints: 

LIBRARY  SEARCH: 

Reply  with  the  list  of  global  symbols  to  be  included  in  the  load 
module;  type  a  carriage  return  to  enter  each  symbol  in  the  list.  A 
carriage  return  alone  terminates  the  list  of  symbols.  This  provides  a 
method  for  forcing  modules  (which  are  not  called  by  other  modules)  to 
be  loaded  from  the  library. 

Example : 


*  o  u  tp  u  r  f  l  p  : = i  n  p  u  r ,  x  l  i  b  ./ 1 


LIBRARY  search:  Linker  prints  LIBRARY  SEARCH: 


A  <CR> 
GETSYM  <CR> 
CHAR  <CR> 
CHFLG  <CR> 
<CR> 


User  enters  A,  GETSYM,  etc.  which  are 
to  be  included  in  the  linking  process. 
Each  symbol  is  entered  by  typing 
a  carriage  return;  the  list  is  termi¬ 
nated  by  an  additional  carriage  return. 
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6.8.6  LDA  Format  Switch 

The  LDA  format  switch  (/L)  causes  the  output  file  to  be  in  LDA  format 
instead  of  save  image  format.  The  LDA  format  file  can  be  output  to 
any  device  including  non-file  structured  devices  such  as  paper  tape  or 
cassette  and  is  useful  for  files  which  are  to  be  loaded  with  the 
Absolute  Loader.  The  default  extension  .LDA  is  assigned  when  the  /L 
switch  is  used. 

The  /L  switch  cannot  be  used  in  conjunction  with  the  overlay  switch 
(/0)  or  in  foreground  links  (/R) . 

Example : 

*  DKJOUT»LPi=INr IN2/L 


6.8.7  Modify  Stack  Address 

The  stack  address,  location  42,  is 
user's  stack  pointer.  The  /M 
specification  of  the  user's  stack  address. 

The  form  of  the  switch  is: 

/M:n 

n  is  an  unsigned  6-digit  octal  number  which  defines  the  stack  address. 
If  n  is  not  specified,  the  Linker  prints  the  message: 

STACK  ADDRESS  = 

In  this  case,  specify  the  global  symbol  whose  value  is  the  stack 
address.  A  number  cannot  be  specified,  and  if  a  nonexistent  symbol  is 
specified,  an  error  message  is  printed  and  the  stack  address  is  set  to 
the  system  default  (1000  for  save  files,  0  for  REL) . 

Direct  assignment  (via  .ASECT)  of  the  stack  address  within  the  program 
takes  precedence  over  assignment  with  the  /M  switch. 

Example : 


Links  disk  files  IN  and  IN2; 
outputs  an  LDA  format  file 
OUT. LDA  to  the  system  device 
and  a  load  map  to  the  line 
printer. 


the  address  which  contains  the 
switch  allows  terminal  keyboard 


♦OUTPUT “INPUT/M 
STACK  ADDRESS  =  BEG 


6.8.8  Overlay  Switch 

The  Overlay  switch  (/O)  is  used  to  segment  the  load  module  so  that  the 
entire  program  is  not  memory  resident  at  one  time  (overlay  feature). 
This  allows  programs  larger  than  the  available  memory  to  be  executed. 
The  switch  has  the  form: 

/0:n 
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where  n  is  an  unsigned  octal  number  (up  to  six  digits  in  length) 
specifying  the  overlay  region  to  which  the  module  is  assigned.  The  /0 
switch  must  follow  (on  the  same  line)  the  specification  of  the  object 
modules  to  which  it  applies,  and  only  one  overlay  region  can  be 
specified  on  a  command  line.  Overlay  regions  cannot  be  specified  on 
the  first  command  line  as  this  is  the  root  segment.  Therefore,  the  /C 
continuation  switch  must  be  used. 

Co-resident  overlay  routines  (a  group  of  subroutines  which  occupy  the 
overlay  region  at  the  same  time)  are  specified  as  follows: 

*0B JA , OB JB , OB JC/O : n/C 

*0BJD,0BJE/0:m/C 


All  modules  mentioned  until  the  next  /0  switch  will  be  co-resident 
overlay  routines.  If  at  a  later  time  the  /0  switch  is  given  with  the 
same  value  previously  used  (same  overlay  region) ,  then  the 
corresponding  overlay  area  is  opened  for  a  new  group  of  subroutines. 
The  new  group  of  subroutines  will  occupy  the  same  locations  in  memory 
as  the  first  group,  but  not  at  the  same  time.  For  example,  if 
subroutines  in  object  modules  R  and  S  are  to  be  in  memory  together, 
but  are  never  needed  at  the  same  time  as  T,  then  the  following 
commands  to  the  Linker  make  R  and  S  occupy  the  same  memory  as  T  (but 
at  different  times): 

#main»lp: «root/c 

#R»S/OU/C 

*  T/o : 1 

The  above  could  also  be  written  as: 

#MA.TNfLP:=ROOT/C 

IR/OU/C 

JKS/C 

* t/o: i 

This  places  S  in  a  different  overlay  segment  in  the  same  region  as  R, 
where  in  the  first  example  S  and  R  are  the  in  the  same  segment. 

Example: 

*  OUTPUT »LPi  =  INPUT/C  Establishes  two  overlay 

*  OBJA/Q i L/C  regions 

*  OBJB/O ♦ 2 

Overlays  must  be  specified  in  order  of  increasing  region  number.  For 
example: 


R  LINK 
*A~A/C 

*e/o:i/c 
*c/on./c 
*d/o:i/c 
*E y  F/0 i 2/C 
*(3/0  J  3 

The  following  overlay  specification  is  illegal  since  the  overlay 
regions  are  given  in  a  random  numerical  order  (an  error  message  is 
printed  in  each  case) : 
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» R  LINK 
♦A “A/C 
#1:1/0 : 2/C 
*B/Oi l/C 
/O  IGNORED 

*c/o: i/c 

/O  IGNORED 
*0/01 3/C 
♦H/0J3/C 
*E f F/0 i 2 
/O  IGNORED 


6.8.9  REL  Format  Switch 

The  REL  format  switch  (/R)  causes  the  output  file  to  be  in  REL  format 
for  use  as  a  foreground  job  under  the  F/B  Monitor.  REL  format  files 
must  be  used  in  a  foreground  job  (they  may  not  be  used  under  a 
Single- Job  system).  The  /R  switch  assigns  the  default  extension  .REL 
to  the  output  file. 

Example t 

*  DT2 » F I  LEO  *  LF'  ♦  “F I  L.E  I » NEX  T/R  Disk  files  FILEI  and  NEXT  are 

linked  and  output  to  DT2  as 
FILEO.REL;  a  load  map  is 
output  to  the  line  printer. 

The  /B  and  /L  switches  cannot  be  used  with  /R  since  a  foreground  REL 
job  has  no  bottom  address  and  is  always  relocated  by  FRUN.  A  ?BAD 
SWITCH?  error  message  is  generated  if  this  is  attempted. 


6.8.10  Symbol  Table  Switch 

Use  of  the  symbol  table  switch  in  the  command  line  instructs  the 
Linker  to  allow  the  largest  possible  memory  area  for  its  symbol  table 
at  the  expense  of  making  the  link  process  slower.  With  the  /S  switch, 
library  directories  are  not  made  resident  in  memory,  but  are  left  on 
disk .  For  example : 

*QUTF » LP S “ INPUT ♦ OBJ , L I BR 1 ♦ OBJ , L I BR2 . OBJ/S 

The  directories  of  the  library  files  LIBR1  and  LIBR2  are  not  brought 
into  memory,  resulting  in  more  room  in  the  symbol  table  but  longer 
link  time. 

If  the  /S  switch  is  not  used  and  the  memory  available  to  the  Linker  is 
10K  or  larger,  the  library  directory  is  brought  into  memory  (providing 
there  is  room) ;  the  directory  is  kept  there  until  the  library  has  been 
completely  processed,  thus  reducing  the  size  of  the  Linker's  symbol 
table.  If  there  is  not  enough  room  in  memory  for  the  directory  (as  is 
the  case  in  an  8K  system) ,  the  Linker  determines  this  and  leaves  the 
directory  on  disk  regardless  of  whether  the  /S  switch  was  used  or  not. 

The  /S  switch  should  be  used  only  if  an  attempt  to  link  a  program 
failed  because  of  symbol  table  overflow.  Often,  use  of  /S  will  allow 
the  program  to  link. 
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6.8.11  Transfer  Address  Switch 

The  transfer  address  is  the  address  at  which  a  program  is  to  be 
started  when  executed  via  an  R,  RUN,  or  FRUN  command.  The  Transfer 
Address  switch  (/T)  allows  terminal  keyboard  specification  of  the 
start  address  of  the  load  module  to  be  executed.  This  switch  has  the 
form: 


/T:n 

where  n  is  a  six-digit  unsigned  octal  number  which  defines  the 
transfer  address.  If  n  is  not  specified,  the  message: 

TRANSFER  ADDRESS  = 

is  printed.  In  this  case,  specify  the  global  symbol  whose  value  is 
the  transfer  address  of  the  load  module,  followed  by  a  carriage 
return.  A  number  cannot  be  specified  in  answer  to  this  message.  When 
a  nonexistent  symbol  is  specified,  an  error  message  is  printed  and  the 
transfer  address  is  set  to  1  (so  that  the  program  cannot  be  executed) . 

If  the  transfer  address  specified  is  odd,  the  program  does  not  start 
after  loading  and  control  returns  to  the  monitor. 

Direct  assignment  (.ASECT)  of  the  transfer  address  within  the  program 
takes  precedence  over  assignment  with  the  /T  switch.  The  transfer 
address  assigned  with  a  /T  has  precedence  over  that  assigned  with  a 
.END  assembly  directive. 

Example: 


*  PR0G=PR0G1 y  PROG 2 1 ODT/T 
TRANSFER  ADDRESS  = 

D .  ODT 


The  files  PR0G1.0BJ,PR0G2.0BJ 
and  ODT. OBJ  are  linked  to¬ 
gether  and  started  at  ODT's 
transfer  address. 


6.9  LINKER  ERROR  HANDLING  AND  MESSAGES 


The  following  error  messages  can  be  output  by  the  Linker.  The 
messages  enclosed  in  question  marks  are  output  to  the  terminal;  the 
other  messages  are  only  warnings  and  are  included  in  the  load  map.  If 
a  load  map  is  not  requested  in  the  command  string,  all  messages  are 
output  to  the  terminal. 


Message  Meaning 

ADDITIVE  REF  OF  xxxxxx  Rule  1  of  overlay  rules  explained  in  Section 

AT  SEG#yyyyyy  6.6  has  been  violated,  xxxxxx  represents  the 

entry  point;  yyyyyy  represents  the  segment 
number. 

?/B  NO  VALUE?  The  /B  switch  reqires  an  octal  number  as  an 

argument. 


?/B  ODD  VALUE? 


The  argument  to  the  /B  switch  was  not  an 
unsigned  even  octal  number. 


?BAD  GSD? 


There  is  an  error  in  the  global  symbol 
directory  (GSD) .  The  file  is  probably  not  a 
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legal  object  module.  This  error  message 
occurs  on  pass  1  of  the  Linker. 

bad  overlay  AT  seg#  yyyyyy 

Overlay  tries  to  store  text  outside  its 


?BAD  RLD? 

region;  check  for  a  .ASECT  in  overlay, 
yyyyyy  represents  the  segment  number. 

There  is  an  invalid  relocation  directory 
(RLD)  command  in  the  input  file;  the  file  is 
probably  not  a  legal  object  module.  The 
message  occurs  on  pass  2  of  the  Linker. 

?BAD  SWITCH? 

LINK  did  not  recognize  a  switch  specified  on 
the  first  command  line.  On  a  subsequent 
command  line,  a  bad  switch  causes  this 
warning  message  but  does  not  restart  the 
Linker. 

?BAD  x  SWITCH  IGNORED? 

LINK  did  not  recognize  a  switch  (x)  specified 
in  the  command  line.  The  switch  is  ignored 
and  linking  continues. 

BYTE  RELOCATION  ERROR  AT  xxxxxx 


Linker  attempted  to  relocate  and  link  byte 
quantities  but  failed,  xxxxxx  represents  the 
address  at  which  the  error  occurred.  Failure 
is  defined  as  the  high  byte  of  the  relocated 
value  (or  the  linked  value)  not  being  all 
zero.  In  such  a  case,  the  value  is  truncated 
to  8  bits  and  the  Linker  continues  processing 
(for  save  image  and  LDA  files  only;  byte 
relocation  is  completely  illegal  for  REL 
files) . 

?CORE? 

There  is  not  enough  memory  to  accommodate  the 
command  or  the  resultant  load  module. 

7ERROR  ERROR? 

An  error  occurred  while  the  Linker  was  in  the 
process  of  recovering  from  a  previous  system 
or  user  error. 

?ERROR  IN  FETCH? 

The  device  is  not  available. 

?FILE  NOT  FND? 

Input  file  was  not  found. 

7F0RLIB  NOT  FND? 

The  user  indicated  via  the  /F  switch  that  the 
FORTRAN  library,  FORLIB,  was  to  be  linked 
with  the  other  object  modules  in  the  command 
line,  and  the  Linker  could  not  find 
FORLIB. OBJ  on  the  system  device. 

7HARD  I/O  ERROR? 

A  hardware  error  occurred;  try  the  operation 
again. 

?ILL  ASECT? 

The  user  has  attempted  to  place  an  .ASECT 
above  1000  in  a  foreground  link  or  to  place 
an  .ASECT  into  an  overlay  foreground  link. 
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?LDA  FILE  ERROR? 


?/M  ODD  VAL? 


?MAP  FILE  ERROR? 


MULT  DEF  OF  XXXXXX 

?NO  INPUT? 

70UTPUT  FULL? 

/O  IGNORED 

?REL  FILE  ERR? 

?SAV  FILE  ERR? 


There  was  a  hardware  problem  with  the  device 
specified  for  LDA  output  or  the  device  was 
full. 

An  odd  value  has  been  specified  for  the  stack 
address.  Control  returns  to  the  Linker  and 
another  command  line  may  be  indicated. 

There  was  a  hardware  problem  with  the  device 
specified  for  map  output  or  the  device  is 
full. 

The  symbol,  xxxxxx,  was  defined  more  than 
once. 

No  input  files  were  specified. 

The  output  device  was  full. 

Overlays  have  been  specified  in  the  wrong 
order  (see  overlay  restrictions) ;  the  overlay 
switch  is  ignored. 

The  Linker  encountered  a  problem  writing  the 
REL  file;  try  the  operation  again. 

The  Linker  encountered  a  problem  writing  the 
save  image  file;  try  the  operation  again. 


7STACK  ADDRESS  UNDEFINED  OR  IN  OVERLAY 

The  stack  address  specified  by  the  /M  switch 
was  either  undefined  or  in  an  overlay.  The 
stack  address  is  set  to  the  system  default. 

7SYMB0L  TABLE  OVERFLOW?  There  were  too  many  global  symbols  used  in 

the  program.  Retry  the  link  using  the  /S 
switch.  If  the  error  still  occurs,  the  link 
cannot  take  place  in  the  available  memory. 

?T00  MANY  OUTPUT  FILES?  The  Linker  allows  specification  of  only  two 

output  files. 

TRANSFER  ADDRESS  UNDEFINED  OR  IN  OVERLAY 

The  transfer  address  was  not  defined  or  was 
in  an  overlay. 

UNDEFINED  GLOBALS  The  globals  listed  (xxxxxx)  were  undefined, 

xxxxxx  If  a  load  map  is  requested,  this  condition 

xxxxxx  also  causes  the  warning  message,  UNDEF  GLBLS, 

,  to  be  printed  on  the  terminal. 
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LIBRARIAN 


The  RT-11  system  provides  the  user  with  the  capability  of  maintaining 
libraries  which  may  be  composed  of  functions  and  routines  of  his 
choice.  Each  library  is  a  file  containing  a  library  header,  library 
directory  (or  entry  point  table) ,  and  one  or  more  object  modules.  The 
object  modules  in  a  library  file  may  be  routines  which  are  repeatedly 
used  in  a  program,  routines  which  are  used  by  more  than  one  program, 
or  routines  which  are  related  and  simply  gathered  together  for  ease  in 
usage — the  contents  of  the  library  file  are  determined  by  the  user's 
needs.  An  example  of  a  typical  library  file  is  the  FORTRAN  library, 
FORLIB  *  OBJ .  This  library  is  provided  with  the  FORTRAN  package  and 
contains  all  the  mathematical  functions  needed  for  normal  usage. 

Object  modules  in  a  library  file  are  accessed  from  another  program  via 
calls  to  their  entry  points;  the  object  modules  are  linked  with  the 
program  which  uses  them  by  the  Linker  (Chapter  6)  to  produce  a  single 
load  module. 


The  RT-11  Librarian  (LIBR)  allows  the  user  to  create,  update,  modify, 
list,  and  maintain  library  files. 


7.1  CALLING  AND  USING  LIBR 

The  RT-11  Librarian  is  called  from  the  system  device  by  entering  the 
command t 

R  LIBR 

in  response  to  the  dot  printed  by  the  Keyboard  Monitor.  The  Command 
String  Interpreter  prints  an  asterisk  at  the  left  margin  on  the 
console  terminal  when  it  is  ready  to  accept  a  command  line. 

Type  CTRL  C  to  halt  the  Librarian  at  any  time  and  return  control  to 
the  monitor.  To  restart  the  Librarian,  type  R  LIBR  or  the  REENTER 
command  in  response  to  the  monitor's  dot. 
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7.2  USER  SWITCH  COMMANDS  AND  FUNCTIONS 

The  user  maintains  library  files  through  the  use  of  switch  commands. 
Functions  which  can  be  performed  include  object  module  deletion, 
insertion  and  replacement,  library  file  creation,  and  listing  of  a 
library  file's  contents. 


7.2.1  Command  Syntax 

LIBR  accepts  command  strings  in  the  following  general  formats 
*dev:lib,dev:list=dev:input/sl/s2/s3 


where : 


devs 

lib 

list 

input 

/si,... 


represents  a  legal  RT-11  device  specification 

represents  the  library  file  to  be  created  or 
updated 

represents  a  listing  file  for  the  library's 
contents 

represents  the  filenames  of  the  input  object 
modules 

represents  one  or  more  of  the  switches  listed 
in  Table  7-1 


Devices  and  filenames  are  specified  by  the  user  in  the  standard  RT-11 
command  string  syntax,  with  default  extensions  assigned  as  follows: 


File 


Extension 


list  file: 
library  file: 
input  files : 


•  LLD 
.OBJ 
.OBJ 


If  no  device  is  specified,  the  default  device  (DK:)  is  assumed. 

Each  input  file  is  made  up  of  one  or  more  object  modules,  and  is 
stored  on  a  given  device  under  a  specific  filename  and  extension. 
Once  an  object  module  has  been  inserted  into  a  library  file,  the 
module  is  no  longer  referenced  by  the  name  of  the  file  of  which  it  was 
a  part,  but  by  its  individual  module  name.  (This  module  name  has  been 
assigned  by  the  assembler  either  via  a  .TITLE  statement  in  the 
assembly  source  program,  or,  if  no  .TITLE  statement  is  present,  with 
the  default  name  .MAIN.;  see  Chapter  5.)  Thus,  for  example,  the  input 
file  FORT. OBJ  may  exist  on  DT2 :  and  may  contain  an  object  module 
called  ABC.  Once  the  module  is  inserted  into  a  library  file, 
reference  is  made  only  to  ABC  (not  FORT. OBJ) . 


7.2.2  LIBR  Switch  Commands 

Table  7-1  summarizes  the  switches  available  for  use  under  RT-11  LIBR. 
Switches  are  explained  in  detail  following  the  table. 
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Table  7-1 
LIBR  Switches 


Switch 

Position  In 
Command  String 

Meaning 

/c 

Any  line 
but  last 

Command  continuation;  the  command  is 
too  long  for  the  current  line  and  is 
continued  on  the  next  line 

/D 

1st  line  only 

Delete;  delete  modules  from  a  library 
file 

/G 

1st  line  only 

Global  deletion;  delete  entry  points 

from  the  library  directory 

/R 

1st  line  only 

Replace;  replace  modules  in  a  library 
file 

/u 

1st  line  only 

Update;  insert  and  replace  modules  in  a 
library  file 

There  is  no  switch  to  indicate  module  insertion.  The  function  of 
inserting  a  module  into  a  library  file  is  assumed  in  the  absence  of 
other  switches. 


7. 2. 2.1  Command  Continuation  Switch  -  The  Command  Continuation  switch 
is  necessary  whenever  there  is  not  enough  room  to  enter  a  command 
string  on  one  line  and  additional  lines  are  needed.  The  /C  switch  is 
typed  at  the  end  of  the  current  line  and  may  be  repeated  at  the  end  of 
subsequent  command  lines  as  often  as  necessary  as  long  as  memory  is 
available;  if  memory  is  exceeded,  an  error  message  is  output.  A  /C 
switch  is  not  entered  on  the  last  line  of  input. 

Command  Format: 

*dev: lib , dev : lis t=dev : input 1 ,dev : input 2 , ...  ,/C 

*dev:inputn 


where : 

dev:  represents  a  device  specification 

lib  represents  the  filename  of  the  library  to  be 
created  or  updated 

list  represents  the  filename  of  a  listing  file  containing 
the  library  file's  contents 

input  represents  the  filenames  of  the  input  modules  to  be 
inserted  into  the  library 

/C  represents  the  Continuation  switch,  indicating 

that  the  command  is  to  be  continued  on  the  following 
line 
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Examples : 


*ALIB»LIBLST»DT1 *  MAIN  *  TEST > FXN/C 
*DT1J TRACK 

In  this  example,  a  library  file  is  created  on  the  default  device  (DKs) 
under  the  filename  ALIB.OBJ;  a  listing  of  the  library  file's  contents 
is  created  as  LIBLST.LLD  also  on  the  default  device;  the  filenames  of 
the  input  modules  are  MAIN. OBJ,  TEST. OBJ,  FXN.OBJ,  and  TRACK. OBJ,  all 
from  DTI. 


♦BLIB--MAIN/C 
*RK1 : TEST/C 
JKRKOJ  FXN/C 
*DTi: TRACK 

A  library  file  is  created  on  the  default  device,  (DKs)  under  the  name 
BLIB.  No  listing  is  produced.  Input  files  are  MAIN  from  the  default 
device,  TEST  from  RKls,  FXN  from  RKO :  and  TRACK  from  DTI: 

Another  way  of  writing  this  command  line  is : 

*BL  I  B~MA I N  r  RK 1  i  TEST  t  RKO  J  FXN/C 
*DT1 J TRACK 


7. 2. 2. 2  Creating  a  Library  File  -  A  library  file  is  created  whenever 
a  filename  is  indicated  on  the  output  side  of  a  command  line  which 
does  not  represent  a  list  file. 

Command  Format: 

* dev:lib=dev: input 1, . . . ,dev:inputn 


where : 

dev:  represents  a  device  specification 

lib  represents  the  filename  of  the  library  to  be  created 

input  represents  the  filenames  of  the  input  modules  to  be 

inserted  into  the  new  library 

Example : 

*  N  E  WL.  IB-FIRST  t  S  E  C  0  N  D 

A  new  library  called  NEWLIB.OBJ  is  created  on  the  default  device 
(DK:).  The  modules  which  will  make  up  this  library  file  are  in  the 
files  FIRST. OBJ  and  SECOND. OBJ,  both  on  the  default  device. 

Assume  this  command  line  is  next  entered: 

♦NEW L I B ,  L. I S T « T H I R D  » F 0 U R T H 

The  already  existing  library  file  NEWLIB  is  destroyed  when  the  new 
library  file  is  created.  A  listing  of  the  library  file's  contents  is 
created  under  the  filename  LIST,  and  the  object  modules  in  the  files 
THIRD  and  FOURTH  are  inserted  into  the  library  file  NEWLIB. 
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7. 2. 2. 3  Inserting  Modules  Into  a  Library  -  The  Insert  function  is 
assumed  whenever  an  input  file  does  not  have  an  associated  switch; 
the  modules  in  the  file  are  inserted  into  the  library  file  named  on 
the  output  side  of  the  command  string.  Any  number  of  input  files  are 
allowed.  If  an  attempt  is  made  to  insert  a  file  which  contains  an 
entry  point  or  .CSECT  having  the  same  name  as  an  entry  point  or  .CSECT 
already  existing  in  the  library  file,  an  error  message  is  printed. 
The  library  file  is  not  updated,  and  control  returns  to  the  CSI;  the 
user  may  enter  another  command  string.  (Refer  to  Section  7. 2. 2. 6  for 
a  method  of  circumventing  this  condition.) 

Although  the  user  may  insert  object  modules  which  exist  under  the  same 
name  (as  assigned  by  the  .TITLE  statement)  this  practice  is  not 
recommended  because  of  the  difficulty  involved  when  replacing  or 
updating  these  modules  (refer  to  Sections  7. 2. 2. 4  and  7. 2. 2. 7). 

NOTE 

The  library  operations  of  module 
insertion,  replacement,  deletion,  merge, 
find  update  are  actually  performed  in 
conjunction  with  the  library  file 
creation  operation.  Therefore,  the 
library  file  to  which  the  operation  is 
directed  must  be  indicated  on  both  the 
input  and  output  sides  of  the  command 
line,  since  effectively  a  "new"  output 
library  file  is  created  each  time  the 
operation  is  performed.  The  library 
file  must  be  specified  first  in  the 
input  field. 

Command  Format: 

*dev:lib=dev:lib,dev:inputl, . . . ,dev:inputn 


where : 

dev:  represents  a  device  specification 

lib  represents  the  filename  of  am  existing  library 

file 

input  represents  the  filenames  of  the  modules  to  be 

inserted  into  the  library  file 

Example: 


*nx Y  -OX Y ,  DT i  i  FA ,  FE< ,  FC 

The  modules  included  in  the  files  FA.OBJ,  FB.OBJ,  and  FC.OBJ  on  DTI: 
are  inserted  into  a  library  file  nauned  DXY.OBJ  on  the  default  device. 
The  library  header  amd  Entry  Point  Table  of  the  library  file  are 
updated  accordingly  (see  Section  7.4). 


7. 2. 2. 4  Replace  Switch  -  The  Replace  function  is  used  to  replace 
modules  in  a  library  file.  All  modules  contained  in  the  file(s) 
indicated  as  input  will  replace  existing  modules  of  the  same  names  in 
the  library  file  specified  as  output. 
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An  error  message  is  printed  and  no  modules  are  replaced  if  an  old 
module  does  not  exist  under  the  same  name  as  an  input  module,  or  if 
the  user  specifies  the  /R  switch  op  a  library  file.  /R  must  follow 
each  input  filename  containing  modules  for  replacement. 

Command  Format: 

*dev : lib=dev : lib , inputl/R, . . . ,dev:inputn/R 

where : 

dev:  represents  a  device  specification 

lib  represents  the  filename  of  an  existing  library 

file 

input  represents  the  names  of  the  files  containing 

modules  to  be  replaced 

/R  represents  the  Replace  switch 

Examples : 

*TFIL=TFIL,INA* INB/R* INC 

This  command  line  indicates  that  the  modules  in  the  file  INB.OBJ  are 
to  replace  existing  modules  of  the  same  names  in  the  library  file 
TFIL.OBJ.  The  object  modules  in  the  files  INA.OBJ  and  INC. OBJ  are  to 
be  added.  All  files  are  stored  on  the  default  device  DK:. 

#XFIL=TFIL> INA» INB/Rf INC 

The  same  operation  occurs  here  as  in  the  preceding  example,  except 
that  this  updated  library  file  is  assigned  the  new  name  XFIL. 


7. 2. 2. 5  Delete  Switch  -  The  Delete  switch  deletes  modules  and  all 
their  associated  entry  points  from  the  library. 

Command  Format : 

*dev : lib=dev : lib/D 

where: 


dev: 

represents 

exists 

the 

device  on 

which  the  library 

file 

lib 

represents 

file 

the 

filename  of  an  existing  library 

/D 

represents 

the 

Delete 

switch;  may 

be 

positioned 

anywhere  on 

the  input  side  of 

the 

command  line 

When  the  /D  switch  is  used,  the  Librarian  prints: 
MOD  NAME: 
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The  user  should  respond  with  the  name  of  the  module  to  be  deleted 
followed  by  a  carriage  return;  he  may  continue  until  all  modules  to 
be  deleted  have  been  entered.  Typing  only  a  carriage  return  (either 
on  a  line  by  itself  or  immediately  after  the  MOD  NAME;  message) 
terminates  input  and  initiates  execution  of  the  command  line. 

Examples : 


*DT3 i TRAP=DT3 MRAP/D 


MOD  NAME ♦ 

SON  <CR> 

TAN  <CR> 

<CR> 

The  modules  SGN.OBJ  and  TAN. OBJ  are  deleted  from  the  library  file 
TRAP. OBJ  on  DT3 :• 


*L IBP IL=LI BF I L/D  t ABC/R r DEF 


MOD  NAME » 

FIRST  <CR> 

<CR> 

The  module  FIRST. OBJ  is  deleted  from  the  library  (LIBFIL) ;  the  module 
ABC. OBJ  replaces  an  old  module  of  the  same  name  in  the  library,  and 
the  modules  in  the  file  DEF. OBJ  are  inserted  into  the  library. 

*LIBFIL»LIBFIL/D 


MOD  NAMEJ 
X  CR> 

X  CR> 

<CR> 

Two  modules  of  the  same  name  are  deleted  from  the  library  file  LIBFIL 
(module  names  are  assigned  with  the  .TITLE  statement  as  described  in 
Section  7.2.1). 


7. 2. 2. 6  Delete  Global  Switch  -  The  Delete  Global  switch  gives  the 
user  the  ability  to  delete  a  specific  entry  point  from  a  library 
file's  Entry  Point  Table. 

Command  Format: 

*dev : lib=dev : lib/G 


where : 


dev: 

represents 

exists 

lib 

represents 

file 

the  device  on  which  the  library  file 
the  filename  of  an  existing  library 
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/G  represents  the  Delete  Global  switch;  may  be 

positioned  anywhere  on  the  input  side  of  the 
command  line 

When  the  /G  switch  is  used,  the  Librarian  prints: 

ENTRY  POINT: 

The  user  should  respond  with  the  name  of  the  entry  point  to  be  deleted 
followed  by  a  carriage  return;  he  may  continue  until  all  entry  points 
to  be  deleted  have  been  entered.  Typing  only  a  carriage  return 
(either  on  a  line  by  itself  or  immediately  after  the  ENTRY  POINT: 
message)  terminates  input  and  initiates  execution  of  the  command  line. 

Example : 

*ROLL=ROLL/G 


ENTRY  POINT; 

NAMEA  <CR> 

NAMED  <CR> 

<CR> 

This  command  instructs  LIBR  to  delete  the  entry  points  NAMEA  and  NAMEB 
from  the  entry  point  table  found  in  the  library  file  ROLL. OBJ  on  DK:. 

As  mentioned  in  Section  7. 2. 2. 3,  if  an  attempt  is  made  to  insert 
modules  into  a  library  file  when  entry  points  within  either  the 
library  file  or  any  of  the  modules  exist  under  duplicate  names,  an 
TILL  INS?  message  is  printed.  To  circumvent  this  condition,  the  /G 
switch  can  be  used  to  delete  all  but  one  of  each  of  the  duplicate 
entry  points. 

For  example,  assume  the  modules  A,  B  and  C  are  to  be  inserted  into  a 
library  file  called  XLIB.  However,  XLIB,  A,  B  and  C- each  contain  an 
entry  point  called  COM1,  and  A,  B  and  C  each  contain  an  entry  point 
called  COM2.  The  following  command  line  is  entered: 

*XLIB=XLIB»A>Bi-C/G 

ENTRY  POINT; 

C0M1  <CR> 

C0M1  <CR> 

CGMl  <CR> 

COM2  <CR> 

COM2  <CR> 

<CR> 

This  deletes  all  but  one  each  of  the  duplicate  entry  points,  allowing 
the  insert  to  take  place. 

Since  entry  points  sure  only  deleted  from  the  Entry  Point  Table  (and 
not  from  the  library  itself)  whenever  a  library  file  is  updated,  all 
entry  points  that  were  previously  deleted  are  restored  unless  the  /G 
switch  is  again  used  to  delete  them.  This  feature  allows  the  user  to 
recover  from  inadvertently  deleting  the  wrong  entry  point. 
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7. 2. 2. 7  Update  Switch  -  The  Update  switch  allows  the  user  to  update  a 
library  file  by  combining  the  insert  and  replace  functions.  If  the 
object  modules  included  in  an  input  file  in  the  command  line  already 
exist  in  the  library  file,  they  are  replaced;  if  not,  they  are 
inserted.  (No  error  messages  are  printed  when  using  the  Update 
function  as  might  occur  under  the  Insert  and  Replace  functions.)  /u 
must  follow  each  input  file  containing  modules  to  be  updated. 

Command  Format: 

*dev : lib=dev : lib , dev : input 1/U , . . . , dev : inputn/U 
where : 

dev:  represents  a  device  specification 

lib  represents  the  filename  of  an  existing  library 


input  represents  the  names  of  files  containing  object 

modules  to  be  updated. 

/U  represents  the  Update  switch 

Examples : 


*BAL.IB=BALIB  > FOLT/U  r  TAL >  BART/U 

This  command  line  instructs  LIBR  to  update  the  library  file  BALIB . OBJ 
on  the  default  device.  First  the  modules  in  FOLT.OBJ  and  BART. OBJ 
replace  old  modules  of  the  same  names  in  the  library  file,  or  if  none 
already  exist  under  their  names,  the  modules  are  inserted.  Then  the 
modules  from  the  file  TAL. OBJ  are  inserted;  an  error  message  is 
printed  if  the  name  of  the  module  in  TAL.OBJ  already  exists. 

*XL.IB--XL..IB/n»Z/U/G 

MOD  NAME i 
X  <CR> 

X  <CR> 

<CR> 


ENTRY  POINT i 
SEC  <CR> 

SEC1  <CR> 

<CR> 

There  are  two  object  modules  of  the  same  name  (X)  in  both  Z  and 
XLIB;  these  are  first  deleted  from  XLIB.  This  ensures  that  both 

modules  X  in  file  Z  are  correctly  placed  into  the  library.  Entry 
points  SEC  and  SEC1  are  also  deleted  from  the  Entry  Point  Table, 
but  automatically  return  when  the  libary  (XLIB)  is  updated. 


7. 2. 2. 8  Listing  the  Directory  of  a  Library  File  -  The  user  may 
specify  that  a  listing  of  the  contents  of  a  library  file  be  output  by 
indicating  both  the  library  file  and  a  list  file  in  the  command  line. 
Since  a  library  file  is  not  being  created  or  updated,  it  is  not 
necessary  to  indicate  the  filename  on  the  output  side  of  the  command 
line;  however  a  comma  must  be  used  to  designate  a  null  output  library 
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Command  Formats: 

*,LP:=dev:lib 

or 

* ,dev : lis t=dev s lib 

where: 

dev:  represents  a  device  specification 

lib  represents  the  file  name  of  an  existing  library  file 

LP:  indicates  the  listing  is  to  be  sent  directly  to  the 

line  printer 

list  represents  a  list  file  of  the  library  file's  contents 

Examples : 


# » 0T2 ♦ LIST=LIBFIL 

This  command  line  outputs  to  DECtape  2  as  LIST.LLD  a  listing  of  the 
contents  of  the  library  file  LIBFIL.OBJ  on  the  default  device. 


* > LP { =FLIB 

This  command  outputs  on  the  line  printer  a  listing  of  all  modules  in 
the  library  file  FLIB.OBJ  stored  on  the  default  device.  Assuming  this 
library  is  composed  of  modules  STOP,  WAIT,  and  IMUL,  is  2  blocks  long, 
was  created  on  September  6,  1974,  and  the  listing  was  requested  on 
September  6,  1974,  the  directory  format  appears  as  follows: 


RT-U  LIBRARIAN  X02-B5 
FLI8 


MODULE 


6.SEP«74 

ENTRY/CSECT 


6*3EP-74 
2  BLOCKS 

ENTRY/CSECT 


ENTRY/CSECT 


STOP 

WAIT 

IMUL 


ST  P  S 
SNAIT 
MUISIS 
MulSSS 


MUISMS 

SMLI 


MUISPS 


7. 2. 2. 9  Merging  Library  Files  -  Two  or  more  library  files  may  be 
merged  under  one  filename  by  indicating  all  the  library  files  to  be 
merged  in  a  single  command  line.  The  individual  library  files  are  not 
deleted  following  the  merge. 

Command  Format: 

*dev:lib=dev:inputl, . . . ,dev:inputn 

where : 

dev:  represents  a  device  specification 

lib  represents  the  name  of  the  library  file  which  will 

contain  all  the  merged  files  (if  a  library  file 
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already  exists  under  this  name,  it  must  also  be 
indicated  in  the  input  side  of  the  command  line  in 
order  to  be  included  in  the  merge) 

input  represents  the  library  files  to  be  merged  together 

Thus,  the  command: 


*MAIN=MAINf TRIG»STP» BAG 


combines  library  files  MAIN. OBJ,  TRIG. OBJ,  STP.OBJ,  and  BAC.OBJ  under 
the  existing  library  file  name  MAIN. OBJ;  all  files  are  on  the  default 
device  DK:. 


*FORT=A»B»C 

This  command  creates  a  library  file  named  FORT. OBJ  and  merges  existing 
library  files  A. OBJ,  B.OBJ,  and  C.OBJ  under  the  filename  FORT. OBJ. 

NOTE 

Library  files  that  have  been  combined 
under  PIP  are  illegal  as  input  to  both 
the  Librarian  and  the  Linker. 


7.3  COMBINING  LIBRARY  SWITCH  FUNCTIONS 

Two  or  more  library  functions  may  be  requested  in  the  same  command 
line.  The  Librarian  performs  functions  in  the  following  order: 

1.  /C 

2.  /D 

3.  /G 

4.  /U 

5.  /R 

6.  Insertions 

7.  Listing 

Example :  , 

# FILE » LP t =FILE/D r  MODX  t MODY/R 


MOD  name: 

XYZ  <CR> 

A  <CR> 

<CR> 

Functions  in  this  example  are  performed  in  order,  as  follows: 

1.  Delete  modules  XYZ. OBJ  and  A. OBJ  from  the  library  file 
FILE. OBJ 

2.  Replace  any  duplicate  of  the  module  in  the  file  MODY.OBJ 

3.  Insert  the  modules  in  the  file  MODX.OBJ 

4.  List  the  contents  of  FILE. OBJ  on  the  line  printer 
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7.4  FORMAT  OF  LIBRARY  FILES 

A  library  file  is  a  contiguous  file  consisting  of  a  header,  an  Entry 
Point  Table  (library  directory)  and  one  or  more  library  object 
modules,  as  illustrated  in  Figure  7-1: 


LIBRARY  HEADER 


ENTRY  POINT  TABLE 


I 

OBJECT  MODULES  | 


LIBRARY  END  TRAILER  BLOCK 


Figure  7-1 

General  Library  File  Format 


The  following  paragraphs  describe  in  detail  each  component  of  a 
library  file. 


7.4.1  Library  Header 


The  header  section  of  a  library  file  contains  17  (decimal)  words  which 
describe  the  current  status  of  the  file  (refer  to  Figure  7-2).  This 
includes  information  relating  to  the  version  of  the  Librarian  in  use, 
the  date  and  time  of  file  creation  or  update,  the  relative  starting 
address  of  the  Entry  Point  Table  (EPT) ,  the  number  of  EPT  entries 
available  and  in  use,  and  the  placing  of  the  next  module  to  be 
inserted  into  the  library  file.  The  contents  of  the  library  header 
are  updated  as  the  library  file  is  modified,  so  that  LIBR  can  always 
quickly  and  easily  access  the  information  it  needs  to  perform  its 
functions.  Figure  7-2  illustrates  the  header  format. 
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1 

56„ 

7 

1 

0 

0 

0 

0 

0 

0 

0 

’28 

XI 

0 

X2 

X  3 

0 

1  F 


1  FORMATTED  BINARY 
>  BLOCK  HEADER 


LIBRARIAN  CODE 
VERSION  NUMBER 


YEAR-MONTH -DAY 


EPT  RELATIVE  START  ADDRESS 

EPT  ENTRIES  ALLOCATED  IN  BYTES 

EPT  ENTRIES  AVAILABLE  (NOT  USED  IN  VERSION  1 

NEXT  INSERT  RELATIVE  BLOCK  NUMBER 

NEXT  BYTE  WITHIN  BLOCK 

NOT  USED 


) 


Figure  7-2 

Library  Header  Format 


7.4.2  Entry  Point  Table  (Library  Directory) 

The  Entry  Point  Table  is  located  immediately  after  the  library  header. 
It  is  composed  of  four-word  entries  which  include  the  names, 
addresses,  and  entry  points  of  all  object  modules  in  the  library  file. 
The  first  two  words  of  an  entry  in  the  EPT  contain  the  Radix  50  name 
by  which  a  module  is  referenced.  The  third  word  provides  a  pointer  to 
the  object  module  where  an  entry  point  is  defined.  The  fourth  word 
contains  the  total  number  of  CSECTs  in  the  object  module  (information 
needed  by  the  Linker) ,  and  the  relative  byte  within  the  block  pointing 
to  the  object  module's  starting  point,  as  shown  in  Figure  7-3. 

The  EPT  is  accessed  sequentially  from  top  to  bottom  whenever  a  library 
module  is  called  by  either  its  module  name  or  an  entry  point. 


0 

SYMBOL  (RAD  50) 

2 

SYMBOL  (RAD  50) 

4 

ADDRESS  OF  BLOCK 

6 

#■  OF  CSECTS  IN 
OBJECT  MODULE 

RELATIVE  BYTE  IN  BLOCK 

BIT  15=  1- MODULE  NAME 

RELATIVE  BYTE  MAXIMUM*  7778 
CSECTS  MAXIMUM  *177g 


Figure  7-3 

Format  of  Entry  Point  Table 
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7.4.3  Object  Modules 

Object  modules  follow  the  Entry  Point  Table.  An  object  module 
consists  of  four  main  types  of  data  blocks:  a  global  symbol 
directory,  text  blocks,  a  relocation  directory,  and  an  internal  symbol 
directory.  The  information  contained  in  these  data  blocks  is  used  by 
the  Linker  during  creation  of  a  load  module. 


7.4.4  Library  End  Trailer 

Following  all  object  modules  in  a  library  file  is  a  specially  coded 
library  end  trailer  which  signifies  the  end  of  the  file.  This  trailer 
is  illustrated  in  Figure  7-4. 


FORMATTED  BINARY  HEADER 
FORMATTED  BINARY  LENGTH 
TYPE  CODE 
NOT  USED 


Figure  7-4 
Library  End  Trailer 


7.5  LIBR  ERROR  MESSAGES 

The  following  error  messages  are  printed  following  incorrect  use  of 
LIBR;  if  any  errors  result  during  library  processing,  the  user  must 
reenter  the  command. 


Message 

Meaning 

?BAD  LIBR? 

The  user  has 

attempted 

to 

build  a 

library  file 

containing 

no 

directory 

entries  or  he 

has  given 

an 

illegally 

constructed 

library 

file 

to  the 

Librarian  as  input. 

?BAD  OBJ?  A  bad  object  module  was  detected  during 

input . 

?CSECT  ERROR?  The  user  has  extended  beyond  the 

allowable  .CSECT  space  for  an  object 
module  to  be  placed  in  the  library 
(i.e.,  the  object  module  contains 
greater  than  127 (decimal)  .CSECTs) . 


7-14 


Librarian 

Message  Meaning 


?DEV  FULL? 

The  device  is  full;  LIBR  is  unable  to 
create  or  update  the  indicated  library 
file.  The  CSI  prints  an  asterisk  and 
waits  for  the  user  to  enter  another 
command  line. 

?FIL  NOT  FND? 

One  of  the  input  files  indicated  in  the 
command  line  was  not  found.  The  CSI 
prints  an  asterisk;  the  command  may  be 
reentered. 

?ILL  CMD? 

An  illegal  command  was  used  in  the 
command  line.  The  CSI  prints  an 
asterisk;  the  command  may  be  reentered. 

xxxxxx  PILL  DEL? 

An  attempt  was  made  to  delete  from  the 
library's  directory  a  module  or  an  entry 
point  that  does  not  exist;  xxxxxx 
represents  the  module  or  entry  point 
name.  The  CSI  prints  an  asterisk  and 
waits  for  the  user  to  enter  another 
command  line. 

PILL  DEV? 

An  illegal  device  was  specified  in  the 
command  line.  The  CSI  prints  an 
asterisk;  the  command  may  be  reentered. 

xxxxxx  PILL  INS? 

An  attempt  was  made  to  insert  a  module 
into  a  library  which  contains  the  same 
entry  point  as  an  existing  module, 
xxxxxx  represents  the  entry  point  name. 
The  CSI  prints  an  asterisk;  a  new 
command  may  be  entered. 

xxxxxx  PILL  REPL? 

An  attempt  was  made  to  replace  in  the 
library  file  a  module  which  does  not 
already  exist.  xxxxxx  represents  the 
module  name.  The  CSI  prints  an  asterisk 
and  waits  for  the  user  to  enter  another 
command  line. 

PIN  ERR? 

An  unrecoverable  hardware/software  error 
has  occurred  while  processing  an  input 
file.  The  CSI  prints  an  asterisk  and 
waits  for  another  command  to  be  entered. 

PLIBR  FIL  ILL  REPL? 

The  user  has  specified  that  a  library 
file  be  replaced  by  another  library 
file.  Only  object  modules  can  be 
replaced. 

?NO  CORE? 

Available  free  memory  has  been  used  up. 
The  current  command  is  aborted  and  the 
CSI  prints  an  asterisk;  a  new  command 
may  be  entered. 

POUT  ERR? 

An  unrecoverable  hardware/software  error 
has  occurred  while  processing  an  output 
file.  The  CSI  prints  an  asterisk  and 
waits  for  the  user  to  enter  another 
command. 
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CHAPTER  8 

ON-LINE  DEBUGGING  TECHNIQUE 


RT-11  On-line  Debugging  Technique  (ODT)  is  a  system  program  that  aids 
in  debugging  assembled  and  linked  object  programs.  Prom  the  keyboard, 
the  user  interacts  with  ODT  and  the  object  program  to: 

1.  Print  the  contents  of  any  location  for  examination  or 
alteration. 

2.  Run  all  or  any  portion  of  an  object  program  using  the 
breakpoint  feature. 

3.  Search  the  object  program  for  specific  bit  patterns. 

4.  Search  the  object  program  for  words  which  reference  a 
specific  word. 

5.  Calculate  offsets  for  relative  addresses. 

6.  Pill  a  single  word,  block  of  words,  byte  or  block  of  bytes 
with  a  designated  value. 

The  assembly  listing  of  the  program  to  be  debugged  should  be  readily 
available  when  ODT  is  being  used.  Minor  corrections  to  the  program 
can  be  made  on-line  during  the  debugging  session,  and  the  program  may 
then  be  run  under  control  of  ODT  to  verify  any  changes  made.  Major 
corrections ,  however  (such  as  a  missing  subroutine) ,  should  be  noted 
on  the  assembly  listing  and  incorporated  in  a  subsequent  updated 
program  assembly. 


8.1  CALLING  AND  USING  ODT 

ODT  is  supplied  as  a  relocatable  object  module.  It  can  be  linked  with 
the  user  program  (using  the  RT-11  Linker)  for  an  absolute  area  in 
memory  and  loaded  with  the  user  program. 

Once  loaded  in  memory  with  the  user  program,  ODT  has  three  legal  start 
or  restart  addresses.  The  lowest  (O.ODT)  is  used  for  normal  entry, 
retaining  the  current  breakpoints.  The  next  (0.0DT+2)  is  a  restart 
address  which  clears  all  breakpoints  and  re-ini tializes  ODT  saving  the 
general  registers  and  clearing  the  relocation  registers.  The  last 
address  (0.0DT+4)  is  used  to  reenter  ODT.  A  reenter  saves  the 
Processor  Status  and  general  registers  and  removes  the  breakpoint 
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instructions  from  the  user  program.  ODT  prints  the  Bad  Entry  (BE) 
error  message.  Breakpoints  which  were  set  are  reset  on  the  next  ;G 
command.  (;P  is  illegal  after  a  BE  message.)  The  ;G  and  ;P  commands 
are  used  to  run  a  program  and  are  explained  in  Section  8.3.7. 

The  absolute  address  used  is  the  address  of  the  entry  point  O.ODT 
shown  in  the  Linker  load  map.  O.ODT  is  always  the  lowest  address  of 
ODT+172,  i.e.,  O.ODT  is  relative  location  172  in  ODT. 


NOTE 

If  linked  with  an  overlay  structured 
file,  ODT  should  reside  in  the  root 
segment  so  it  is  always  in  memory.  A 
breakpoint  inserted  in  an  overlay  will 
be  destroyed  if  it  is  overlaid  during 
program  execution. 


If  ODT  is  being  used  in  a  Foreground/Background  environment  with 
another  job  running,  ODT's  priority  bit  must  be  set  to  0  as  follows: 

*$P, '60008?  0  <CR> 

This  puts  ODT  into  the  wait  state  at  level  0,  not  7.  If  this  is  not 
done,  all  interrupts  (including  clock)  will  be  locked  out  while  ODT  is 
waiting  for  terminal  input. 


Examples : 


1. 


ODT  Linked  with  the  User  Program: 


. GET  USER. SRV 
.  START  1172 

OPT  V81-01 

* 


User  program  previously  linked  to 
ODT  is  brought  into  memory. 

Value  (1172)  of  entry  point  O.ODT 
(determined  from  Linker  load  map) 
is  used  to  start  ODT. 


2.  Loading  ODT  with  the  User  Program: 


.  GET  USER.  SRV 
.  GET  ODT.  SRV 
.  STRRT  1172 


User  program  is  loaded  into  memory. 

ODT  is  loaded  into  memory. 

Assuming  ODT  has  been  linked  for  a 
bottom  address  of  1000,  ODT  starts. 


OPT  V61-01 

* 

3.  Restarting  ODT  Clearing  Breakpoints: 

STrrt  1174  Assuming  ODT  was  originally 

linked  for  a  bottom  address  of  1000, 
*  this  command  (O.ODT+2) 

—  re-initializes  ODT  and  clears  any 

previous  breakpoints. 
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4 .  Reentering  ODT s 

•  START  1176  Assuming  ODT  was  linked  for  a 

bottom  address  of  1000,  the  value 
BE081212  of  O.ODT  1172+4  is  used  as  the 

*  s  tart  addr es  s . 

5.  Using  ODT  with  Foreground/Background  Jobs: 

It  is  possible  to  use  ODT  to  debug  programs  written  as  either 
background  or  foreground  jobs.  In  the  background  or  under 
the  Single- Job  Monitor,  ODT  can  be  linked  with  the  program  as 
described  in  Example  1  above. 


To  debug  a  program  in  the  foreground  area,  it  is  recommended 
that  ODT  be  run  in  the  background  while  the  program  to  be 
debugged  is  in  the  foreground.  The  sequence  of  commands  to 
do  this  is : 


^FRUN  PROGVP 
LORDED  ft T  xxxxxx 

L RUN  ODT 

OPT  V01-01 

* XXXXXX; 0R 

*  *1 F / 006Q06  6<CR> 
*0;  G 

.  RSU 


Load  the  foreground  program. 

The  first  address  of  the  job  is 
printed  (xxxxxx) 

Run  ODT  in  the  background 
and  set  a  relocation  register 
to  the  start  of  the  job.  $F 
is  the  format  register.  It 
should  be  cleared  to  enable  proper 
address  print  out.  0;G  starts  the 
Keyboard  Monitor  again,  and  .RSU 
starts  the  foreground  job. 


The  copy  of  ODT  used  must  be  linked  low  enough  so  that  it 
will  fit  in  memory  along  with  the  foreground  job. 


NOTE 

Since  ODT  uses  its  own  terminal  handler, 
it  cannot  be  used  with  the  display 
hardware.  If  GT  ON  has  been  typed,  ODT 
will  ignore  it  and  direct  I/O  only  to 
the  console  terminal. 


8.1,1  Return  to  Monitor,  CTRL  C 

If  ODT  is  awaiting  a  command,  a  CTRL  C  from  the  keyboard  calls  the 
RT-11  Keyboard  Monitor.  The  monitor  responds  with  a  tC  on  the 
terminal  and  awaits  a  Keyboard  Monitor  command.  (The  monitor  REENTER 
command  may  be  used  to  reenter  ODT  only  if  the  user  program  has  set 
the  reenter  bit.  Otherwise  ODT  is  reentered  at  address  O.ODT+4  as 
shown  above . ) 
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8.1.2  Terminate  Search,  CTRL  U 

If  typed  during  a  search  printout,  a  CTRL  U  terminates  the  search  and 
ODT  prints  an  asterisk. 


8.2  RELOCATION 

When  the  assembler  produces  a  binary  object  module,  the  base  address 
of  the  module  is  taken  to  be  location  000000,  and  the  addresses  of  all 
program  locations  as  shown  in  the  assembly  listing  cure  indicated 
relative  to  this  base  address.  After  the  module  is  linked  by  the 
Linker,  many  values  within  the  program,  and  all  the  addresses  of 
locations  in  the  program,  will  be  incremented  by  a  constant  whose 
value  is  the  actual  absolute  base  address  of  the  module  after  it  has 
been  relocated.  This  constant  is  called  the  relocation  bias  for  the 
module.  Since  a  linked  program  may  contain  several  relocated  modules 
each  with  its  own  relocation  bias,  and  since,  in  the  process  of 
debugging,  these  biases  will  have  to  be  subtracted  from  absolute 
addresses  continually  in  order  to  relate  relocated  code  to  assembly 
listings,  RT-11  ODT  provides  an  automatic  relocation  facility. 

The  basis  of  the  relocation  facility  lies  in  eight  relocation 
registers,  numbered  0  through  7,  which  may  be  set  to  the  values  of  the 
relocation  biases  at  different  times  during  debugging.  Relocation 
biases  should  be  obtained  by  consulting  the  memory  map  produced  by  the 
Linker.  Once  set,  a  relocation  register  is  used  by  ODT  to  relate 
relocatable  code  to  relocated  code.  For  more  information  on  the  exact 
nature  of  the  relocation  process,  consult  Chapter  6,  the  RT-11  Linker. 


8.2.1  Relocatable  Expressions 

A  relocatable  expression  is  evaluated  by  ODT  as  a  16-bit  (6-digit 
octal)  number  and  may  be  typed  in  any  one  of  the  three  forms  presented 
in  Table  8-1.  In  this  table,  the  symbol  n  stands  for  an  integer  in  the 
range  0  to  7  inclusive,  and  the  symbol  k  stands  for  an  octal  number  up 
to  six  digits  long,  with  a  maximum  value  of  177777.  If  more  than  six 
digits  are  typed,  ODT  takes  the  last  six  digits,  truncated  to  the 
low-order  16  bits,  k  may  be  preceded  by  a  minus  sign,  in.  which  case 
its  value  is  the  two's  complement  of  the  number  typed.  For  example: 


k  (number  typed) 


Values 


1 

-1 

400 

-177730 

1234567 


000001 

177777 

000400 

000050 

034567 
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Table  8-1 

Forms  of  Relocatable  Expressions  (r) 


r 

Value  of  r 

A) 

k 

The  value  of  r  is  simply  the  value  of  k. 

B) 

n,k 

The  value  of  r  is  the  value  of  k  plus 
the  contents  of  relocation  register  n. 

If  the  n  part  of  this  expression  is 

greater  than  7,  ODT  uses  only  the  last 
octal  digit  of  n. 

C) 

C  or 

Whenever  the  letter  C  is  typed,  ODT 

C,k  or 

replaces  C  with  the  contents  of  a 

n,C  or 

special  register  called  the  Constant 

C,C 

Register.  This  value  has  the  same  role 
as  the  k  or  n  that  it  replaces  (i.e., 
when  used  in  place  of  n  it  designates  a 
relocation  register).  The  Constant 
Register  is  designated  by  the  symbol  $C 

and  may  be  set  to  any  value,  as 
indicated  below. 

In  the  following  examples,  assume  in  each  case  that  relocation 
register  3  contains  003400  and  that  the  constant  register  contains 
000003. 


r 

Value  < 

5;C 

000005 

-17  ;C 

177761 

3,0;C 

003400 

3,150;C 

003550 

3,-l;C 

003377 

C;C 

000003 

3,C;C 

003403 

C,0;C 

003400 

C,10;C 

003410 

C,C;C 

003403 

NOTE 

For  simplicity  most  examples  in  this 
section  use  Form  A.  All  three  forms  of  r 
are  equally  acceptable,  however. 

8.3  COMMANDS  AND  FUNCTIONS 

When  ODT  is  started  (as  explained  in  Section  8.1)  it  indicates 
readiness  to  accept  commands  by  printing  an  asterisk  on  the  left 
margin  of  the  terminal  page.  Most  of  the  ODT  commands  can  be  issued 
in  response  to  the  asterisk.  For  example,  a  word  can  be  examined  and 
changed  if  desired,  the  object  program  can  be  run  in  its  entirety  or 
in  segments ,  or  memory  can  be  searched  for  certain  words  or  references 
to  certain  words.  The  discussion  below  explains  these  features.  In 
the  following  examples,  characters  output  by  ODT  are  underlined  to 
differentiate  from  user  input. 

8.3.1  Printout  Formats 

Normally,  when  ODT  prints  addresses  (as  with  the  commands  4.,  t, 

<,  and  >)  it  attempts  to  print  them  in  relative  form  (Form  B  in  Table 
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8-1) .  ODT  looks  for  the  relocation  register  whose  value  is  closest  but 
less  than  or  equal  to  the  address  to  be  printed,  and  then  represents 
the  address  relative  to  the  contents  of  the  relocation  register. 
However,  if  no  relocation  register  fits  the  requirement,  the  address 
is  printed  in  absolute  form.  Since  the  relocation  registers .  are 
initialized  to  -1  (the  highest  number)  the  addresses  are  initially 
printed  in  absolute  form.  If  any  relocation  register  subsequently  has 
its  contents  changed,  it  may  then,  depending  on  the  command,  qualify 
for  relative  form. 

For  example,  suppose  relocation  registers  1  and  2  contain  1000  and 
1004  respectively,  and  all  other  relocation  registers  contain  numbers 
much  higher.  Then  the  following  sequence  might  occur  (the  slash 
command  causes  the  contents  of  the  location  to  be  printed;  the  line 
feed  command  (<LF>)  accesses  the  next  sequential  location) s 


*774/000000  <LF> 
000776  ,-'060008  <LF> 
1,000000  7000000  <LF> 
1, 000002  7000000  <LF> 
2, 000000  7000060 


(absolute  location  1000) 
(absolute  location  1002) 
(absolute  location  1004) 


The  printout  format  is  controlled  by  the  format  register,  $F.  Normally 
this  register  contains  0 ,  in  which  case  ODT  prints  addresses 
relatively  whenever  possible.  $F  may  be  opened  and  changed  to  a 
non-zero  value,  however,  in  which  case  all  addresses  will  be  printed 
in  absolute  form  (see  paragraph  8.3.4,  Accessing  Internal  Registers). 


8.3.2  Opening,  Changing,  and  Closing  Locations 

An  open  location  is  one  whose  contents  ODT  prints  for  examination, 
making  those  contents  available  for  change.  In  a  closed  location,  the 
contents  are  no  longer  available  for  change.  Several  commands  are 
used  for  opening  and  closing  locations. 

Any  command  used  to  open  a  location  when  another  location  is  already 
open  causes  the  currently  open  location  to  be  closed.  The  contents  of 
an  open  location  may  be  changed  by  typing  the  new  contents  followed  by 
a  single-character  command  which  requires  no  argument  (i.e.,  <LF>  ,  t, 
RETURN,  @,  >,  <)  . 


The  Slash,  / 

One  way  to  open  a  location  is  to  type  its  address  followed  by  a  slash: 


*10067012746 


Location  1000  is  open  for  examination  and  is  available  for  change. 

If  the  contents  of  an  open  location  are  not  to  be  changed,  type  the 
RETURN  key  and  the  location  is  closed;  ODT  prints  an  asterisk  and 
waits  for  another  command.  However,  to  change  the  word,  simply  type 
the  new  contents  before  giving  a  command  to  close  the  location: 


*10007012746  612345  <CR> 
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In  the  example  above,  location  1000  now  contains  012345  and  is  closed 
since  the  RETURN  key  was  typed  after  entering  the  new  contents,  as 
indicated  by  ODT's  second  asterisk. 

Used  alone,  the  slash  reopens  the  last  location  opened: 

*1680/012345  2340  <CR> 

*/M12M 

In  the  example  above,  the  open  location  was  closed  by  typing  the 
RETURN  key.  ODT  changed  the  contents  of  location  1000  to  002340  and 
then  closed  the  location  before  printing  the *  *.  The  single  slash 
command  directed  ODT  to  reopen  the  last  location  opened.  This  allowed 
verification  that  the  word  002340  was  correctly  stored  in  location 
1000. 

Note  again,  that  opening  a  location  while  another  is  open 
automatically  closes  the  currently  open  location  before  opening  the 
new  location. 

Also  note  that  if  an  odd  numbered  address  is  specified  with  a  slash, 
ODT  opens  the  location  as  a  byte,  and  subsequently  behaves  as  if  a 
backslash  had  been  typed  (see  the  following  paragraph) . 


The  Backslash,  \ 

In  addition  to  operating  on  words,  ODT  operates  on  bytes.  One  way  to 
open  a  byte  is  to  type  the  address  of  the  byte  followed  by  a 
backslash.  (On  the  LT33  or  LT35  terminal  \  is  typed  by  pressing  the 
SHIFT  key  while  typing  the  L  key.)  This  causes  not  only  the  printing 
of  the  byte  value  at  the  specified  address  but  also  the  interpreting 
of  the  value  as  ASCII  code,  and  the  printing  of  the  corresponding 
character  (if  possible)  on  the  terminal: 

*1001 S 161  =0 

A  backslash  typed  alone  reopens  the  last  open  byte.  If  a  word  was 
previously  open,  the  backslash  reopens  its  even  byte: 

*1602/060064  \ 0 0 4  = 


The  LINE  FEED  Key, <LF> 

If  the  LINE  FEED  key  is  typed  when  a  location  is  open,  ODT  closes  the 
open  location  and  opens  the  next  sequential  location: 

*1086/6023:40  <LF>  (  <LF>  denotes  typing  the  LINE  FEED  key) 
601002  / 012746 

In  this  example,  the  LINE  FEED  key  caused  ODT  to  print  the  address  of 
the  next  location  along  with  its  contents,  and  to  wait  for  further 
instructions.  After  the  above  operation,  location  1000  is  closed  and 
1002  is  open.  The  open  location  may  be  modified  by  typing  the  new 
contents • 

If  a  byte  location  was  open,  typing  the  LINE  FEED  key  opens  the  next 
byte  location. 
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The  Up- Arrow,  t  or 

If  the  up-arrow  (or  circumflex)  is  typed  when  a  location  is  open 
(up-arrow  is  produced  on  an  LT33  or  LT35  by  typing  SHIFT  N)  ,  ODT  closes 
the  open  location  and  opens  the  previous  location.  To  continue  from 
the  example  above: 

*861002/612740  t 
801808  /662I<40 

Now  location  1002  is  closed  and  1000  is  open.  The  open  location  may 
be  modified  by  typing  the  new  contents. 

If  the  opened  location  was  a  byte,  then  up-arrow  opens  the  previous 
byte. 


The  Back- Arrow,  «-  or  _ 


If  the  back-arrow  (or  underline)  is  typed  (via  SHIFT  0  on  an  LT33  or 
LT35  terminal)  to  an  open  word,  ODT  interprets  the  contents  of  the 
currently  open  word  as  an  address  indexed  by  the  Program  Counter  (PC) 
and  opens  the  addressed  location: 

*1066/080006  <- 
801816  7860405 

Notice  in  this  example  that  the  open  location,  1006,  was  indexed  by 
the  PC  as  if  it  were  the  operand  of  an  instruction  with  address  mode 
67  as  explained  in  Chapter  5. 

A  modification  to  the  opened  location  can  be  made  before  a  line  feed, 
up-arrow,  or  back-arrow  is  typed.  Also,  the  new  contents  of  the 
location  will  be  used  for  address  calculations  using  the  back-arrow 
command.  Example: 

*100/066222  4  <LF>  (modify  to  4  and  open  next  location) 
086182  / 8 8 8 1 1 1  6 f  (modify  to  6  and  open  previous  location) 

860180  / 6 0 0 6 8 4  160* *-  (change  to  100  and  open  location  indexed 
088282  / 1 2 3 4 5 6  by  PC) 


Open  the  Addressed  Location,  @ 

The  at  symbol  @  (SHIFT  P  on  the  LT33  or  LT35  terminal)  may  be  used  to 
optionally  modify  a  location,  close  it,  and  then  use  its  contents  as 
the  address  of  the  location  to  open  next. 

*1866/661044  &  (open  location  1044  next) 

601844  / 8 0 6 5 0 0 

*1006/061044  21068  (modify  to  2100  and  open  location 

002108  / 000167  2100) 
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Relative  Branch  Offset,  > 


The  right-angle  bracket,  >,  will  optionally  modify  a  location,  close 
it,  and  then  use  its  low-order  byte  as  a  relative  branch  offset  to  the 
next  word  to  be  opened.  For  example: 

*1832 (''680467  361>  (modify  to  301  and  interpret  as  a 
666636  /600610  relative  branch) 

Note  that  301  is  a  negative  offset  (-77) .  The  offset  is  doubled  before 
it  is  added  to  the  PC;  therefore,  1034+ (-176) =636. 


Return  to  Previous  Sequence ,  < 

The  left-angle  bracket,  <,  allows  the  user  to  optionally  modify  a 
location,  close  it,  and  then  open  the  next  location  of  the  previous 
sequence  which  was  interrupted  by  a  back-arrow,  @,  or  right-angle 
bracket  command.  Note  that  back-arrow,  @,  or  right-angle  bracket 
causes  a  sequence  change  to  the  word  opened.  If  a  sequence  change  has 
not  occurred,  the  left-angle  bracket  simply  opens  the  next  location  as 
a  LINE  FEED  does.  This  command  operates  on  both  words  and  bytes. 


*10327066407  361> 


000636 

/000010 

< 

001034 

/  0  0 1 0  4  0 

001040 

/  0  0  0  4  0  5 

X005  =  < 

001035 

\002  =  < 

001036 

S004  = 

(>  causes  a  sequence  change) 
(return  to  original  sequence) 
(@  causes  a  sequence  change) 
(<  now  operates  on  byte) 

(<  acts  like  <LF>) 


8.3.3  Accessing  General  Registers  0-7 


The  program's  general  registers  0-7  are  opened  with  a  command  in  the 
following  format: 


*$n/ 


where  n  is  the  integer  representing  the  desired  register  (in  the  range 
0  through  7) .  When  opened,  these  registers  can  be  examined  or  changed 
by  typing  in  new  data  as  with  any  addressable  location.  For  example: 

*$0/000033  <CR>  (R0  was  examined  and  closed) 

i 

*$ 4/680474  464<CR>  (R4  was  opened,  changed,  and  closed) 

* 

The  example  above  can  be  verified  by  typing  a  slash  in  response  to 
ODT's  asterisk: 

*7000464 

The  LINE  FEED,  up-arrow,  back-arrow  or  @  command  may  be  used  when  a 
register  is  open. 
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8.3.4  Accessing  Internal  Registers 

The  program's  Status  Register  contains  the  condition  codes  of  the  most 
recent  operational  results  and  the  interrupt  priority  level  of  the 
object  program.  It  is  opened  by  typing  $S.  For  example: 

*<5/088311 

$S  represents  the  address  of  the  Status  Register.  In  response  to  $S 
in  the  example  above,  ODT  printed  the  16-bit  word,  of  which  only  the 
low-order  eight  bits  are  meaningful.  Bits  0-3  indicate  whether  a 
carry,  overflow,  zero,  or  negative  (in  that  order)  has  resulted,  and 
bits  5-7  indicate  the  interrupt  priority  level  (in  the  range  0-7)  of 
the  object  program.  (Refer  to  the  PDP-11  PROCESSOR  HANDBOOK  for  the 
Status  Register  format.) 

The  $  is  used  to  open  certain  other  internal  locations  listed  in  Table 
8-2: 


Table  8-2 
Internal  Registers 


Register 

Function 

$B 

location  of  the  first  word  of  the  breakpoint  table 

(see  Section  8.3.6). 

$M 

mask  location  for  specifying  which  bits  are  to  be 
examined  during  a  bit  pattern  search  (see  Section 

8.3.9)  . 

$P 

location  defining  the  operating  priority  of  ODT 
(see  Section  8.3.15). 

$s 

location  containing  the  condition  codes  (bits  0-3) 
and  interrupt  priority  level  (bits  5-7)  (explained 
above) . 

$c 

location  of  the  Constant  Register  (see  Section 

8.3.10) . 

$R 

location  of  Relocation  Register  0 ,  the  base  of  the 
Relocation  Register  table  (see  Section  8.3.13). 

$F 

location  of  Format  Register  (see  Section  8.3.1). 

8.3.5  Radix  50  Mode,  X 

The  Radix  50  mode  of  packing  certain  ASCII  characters  three  to  a  word 
is  employed  by  many  DEC-supplied  PDP-11  system  programs,  and  may  be 
employed  by  any  programmer  via  the  MACRO  Assembler's  ".RAD50" 
directive.  ODT  provides  a  method  for  examining  and  changing  memory 
words  packed  in  this  way  with  the  X  command. 

When  a  word  is  opened  and  the  X  command  is  typed,  ODT  converts  the 
contents  of  the  opened  word  to  its  3-character  Radix  50  equivalent  and 
prints  these  characters  on  the  terminal.  One  of  the  responses  in 
Table  8-3  can  then  be  typed: 
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Table  8-3 

Radix  50  Terminators 


Response 

Effect 

RETURN  key  <CR> 

Closes  the  currently  open  location. 

LINE  FEED  key  <LF> 

Closes  the  currently  open  location 
opens  the  next  one  in  sequence. 

and 

t  key 

Closes  the  currently  open  location 
opens  the  previous  one  in  sequence. 

and 

Any  three 

Converts  the  three  specified  characters 

characters  whose 
octal  code  is  040 
(space)  or  greater. 

into  packed  Radix  50  format. 

Legal  Radix  50  characters  for  this  last  response  are: 

.  $  Space 

0  through  9  A  through  Z 

If  any  other  characters  are  typed ,  the  resulting  binary  number  is 
unspecified  (that  is,  no  error  message  is  printed  and  the  result  is 
unpredictable) •  Exactly  three  characters  must  be  typed  before  ODT 
resumes  its  normal  mode  of  operation.  After  the  third  character  is 
typed,  the  resulting  binary  number  is  available  to  be  stored  in  the 
opened  location  by  closing  the  location  in  any  one  of  the  ways  listed 
in  Table  8-3.  Example: 

*1000/042431  X  =  K B I  CBfl  <CR> 

*1000/011421  X=CBR 


NOTE 

After  ODT  has  converted  the  three 
characters  to  binary,  the  binary  number 
can  be  interpreted  in  one  of  many 
different  ways,  depending  on  the  command 
which  follows.  For  example: 

*1234 / 0 6 3 3 3 7  X  =  PRCl  X I  T /813704 

Since  the  Radix  50  equivalent  of  XIT  is 
113574,  the  final  slash  in  the  example 
will  cause  ODT  to  open  location  113574 
if  it  is  a  legal  address.  (Refer  to 
paragraph  8.5  for  a  discussion  of 
command  legality  and  detection  of 
errors. ) 


8.3.6  Breakpoints 

The  breakpoint  feature  facilitates  monitoring  the  progress  of  program 
execution.  A  breakpoint  may  be  set  at  any  instruction  which  is  not 
referenced  by  the  program  for  data.  When  a  breakpoint  is  set,  ODT 
replaces  the  contents  of  the  breakpoint  location  with  a  trap 
instruction  so  that  program  execution  is  suspended  when  a  breakpoint 
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is  encountered.  The  original  contents  of  the  breakpoint  location  are 
restored ,  and  ODT  regains  control. 

With  ODT,  up  to  eight  breakpoints,  numbered  0  through  7,  can  be  set  at 
any  one  time.  A  breakpoint  is  set  by  typing  the  address  of  the 
desired  location  of  the  breakpoint  followed  by  ;B.  Thus  r;B  sets  the 
next  available  breakpoint  at  location  r.  (If  all  8  breakpoints  have 
been  set,  ODT  ignores  the  r;B  command.)  Specific  breakpoints  may  be 
set  or  changed  by  the  r;nB  command  where  n  is  the  number  of  the 
breakpoint.  For  examples 

♦  1820;  B 
♦1030; B 
♦1040; B 
♦1032; IB 

♦ 

The  ;B  command  removes  all  breakpoints.  Use  the  ;nB  command  to  remove 
only  one  of  the  breakpoints,  where  n  is  the  number  of  the  breakpoint. 
For  example: 

♦  ;  2B  (removes  the  second  breakpoint) 

♦ 

A  table  of  breakpoints  is  kept  by  ODT  and  may  be  accessed  by  the  user. 
The  $B/  command  opens  the  location  containing  the  address  of 
breakpoint  0.  The  next  seven  locations  contain  the  addresses  of  the 
other  breakpoints  in  order,  and  can  be  sequentially  opened  using  the 
LINE  FEED  key.  For  example: 

♦ $6/001020  <LF> 
nnnnnn  /061632  <LF> 

nnnnnn  /nnnnnn  (nnnnnn=address  internal  to  ODT) 

In  this  example,  breakpoint  2  is  not  set.  The  contents  printed  is  an 
address  internal  to  ODT  and  can  be  determined  by  checking  the  Linker 
Load  Map  (see  Chapter  6). 

It  should  be  noted  that  a  repeat  count  in  a  Proceed  command  refers 
only  to  the  breakpoint  that  has  most  recently  occurred.  Execution  of 
other  breakpoints  encountered  is  determined  by  their  own  repeat 
counts . 


(sets  breakpoint  0) 
(sets  breakpoint  1) 
(sets  breakpoint  2) 
(resets  breakpoint  1) 


8.3.7  Running  the  Program,  r;G  and  r;P 

Program  execution  is  under  control  of  ODT.  There  are  two  commands  for 
running  the  program:  r;G  and  r?P.  The  r?G  command  is  used  to  start 

execution  (Go)  and  r?P  to  continue  (Proceed)  execution  after  halting 
at  a  breakpoint.  For  example: 

♦1000; G 

Execution  is  started  at  location  1000.  The  program  runs  until  a 
breakpoint  is  encountered  or  until  program  completion,  unless  it  gets 
caught  in  an  infinite  loop,  in  which  case  it  must  be  either  restarted 
or  reentered  as  explained  in  Section  8.1. 

Upon  execution  of  either  the  r;G  or  r;P  command,  the  general  registers 
0-6  are  set  to  the  values  in  the  locations  specified  as  $0-$6  and  the 
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processor  Status  Register  is  set  to  the  value  in  the  location 
specified  as  $S. 


When  a  breakpoint  is  encountered,  execution  stops  and  ODT  prints  Bn; 
(where  n  is  the  breakpoint  number),  followed  by  the  address  of  the 
breakpoint.  Locations  can  then  be  examined  for  expected  data.  For 
example : 


*1010; 3B 
*1000;  G 
B3; 001010 

* 


(breakpoint  3  is  set  at  location  1010) 
(execution  started  at  location  1000) 
(execution  stopped  at  location  1010) 


To  continue  program  execution  from  the  breakpoint,  type  ;P  in  response 
to  ODT's  last  *. 


When  a  breakpoint  is  set  in  a  loop,  it  may  be  desirable  to  allow  the 
program  to  execute  a  certain  number  of  times  through  the  loop  before 
recognizing  the  breakpoint.  This  can  be  done  by  setting  a  proceed 
count  using  the  k;P  command;  this  command  specifies  the  number  of 
times  the  breakpoint  is  to  be  encountered  before  program  execution  is 
suspended  (on  the  kth  encounter).  The  count,  k,  refers  only  to  the 
numbered  breakpoint  which  most  recently  occurred.  A  different  proceed 
count  may  be  specified  for  the  breakpoint  when  it  is  encountered. 
Thus : 


63; 001010 

*1026; 36 
*4;  P 

63; 001026 

* 


(execution  halted  at  breakpoint  3) 
(reset  breakpoint  3  at  location  1026) 
(set  proceed  count  to  4  and 
continue  execution;  loop  through 
breakpoint  three  times  and  halt  on 
fourth  occurrence  of  the  breakpoint) 


Following  the  table  of  breakpoints  (as  explained  in  Section  8.3.6)  is 
a  table  of  proceed  command  repeat  counts  for  each  breakpoint.  These 
repeat  counts  can  be  inspected  by  typing  $B/  and  nine  LINE  FEEDS.  The 
repeat  count  for  breakpoint  0  is  printed  (the  first  seven  LINE  FEEDS 
cause  the  table  of  breakpoints  to  be  printed;  the  eighth  types  the 
single  instruction  mode,  explained  in  the  next  section,  and  the  ninth 
LINE  FEED  begins  the  table  of  proceed  command  repeat  counts).  The 
repeat  counts  for  breakpoints  1  through  7,  and  the  repeat  count  for 
the  single-instruction  trap  follow  in  sequence.  Before  a  proceed 
count  is  assigned  a  value  by  the  user,  it  is  set  to  0;  after  the  count 
has  been  executed,  it  is  set  to  -1.  Opening  any  one  of  these  provides 
an  alternative  way  of  changing  the  count  as  the  location,  once  open, 
can  have  its  contents  modified  in  the  usual  manner  by  typing  the  new 
contents  and  then  the  RETURN  key.  For  example: 


nnnnnn 

/  0  0 1 0  3  6 

<LF> 

nnnnnn 

/0066K0 

<LF> 

nnnnnn 

/  0  0  0  0  0  0 

15  <LF> 

nnnnnn 

,• '000000 

<LF> 

nnnnnn 

( 

t 

✓000000 

<LF> 

nnnnnn 

/nnnnnn 

(address  of  breakpoint  7) 

(single  instruction  address) 

(count  for  breakpoint  0;  change  to  15) 
(count  for  breakpoint  1) 


(count  for  breakpoint  7) 

(repeat  count  for  single  instruction 
mode;  the  single  instrucion  address 
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is  an  address  internal  to  the  user 
program  if  single  instrucion  mode  is 
used) 


The  address  indicated  as  the  single  instruction  address  and  the  repeat 
count  for  single  instruction  mode  are  explained  next. 


8.3.8  Single  Instruction  Mode 

With  this  mode  the  number  of  instructions  to  be  executed  before 
suspension  of  the  program  run  can  be  specified.  The  Proceed  command , 
instead  of  specifying  a  repeat  count  for  a  breakpoint  encounter, 
specifies  the  number  of  succeeding  instructions  to  be  executed.  Note 
that  breakpoints  are  disabled  when  single  instruction  mode  is 
operative. 

Commands  for  single  instruction  mode  are: 


Enables  single  instruction  mode  (n  can  have  any 
non-zero  value  and  serves  only  to  distinguish  this 
form  from  the  form  ;S) •  Breakpoints  are  disabled. 


nS 


Proceeds  with  program  run  for  next  n  instructions 
before  reentering  ODT  (if  n  is  missing,  it  is 
assumed  to  be  1).  Trap  instructions  and  associated 
handlers  can  affect  the  Proceed  repeat  count.  See 
Section  8.4.2. 


n?P 


Disables  single  instruction  mode. 


When  the  repeat  count  for  single  instruction  mode  is  exhausted  and  the 
program  suspends  execution,  ODT  prints: 


B8;nnnnnn 


where  nnnnnn  is  the  address  of  the  next  instruction  to  be  executed. 
The  $B  breakpoint  table  contains  this  address  following  that  of 
breakpoint  7.  However,  unlike  the  table  entries  for  breakpoints  0-7, 
direct  modification  has  no  effect. 

Similarly,  following  the  repeat  count  for  breakpoint  7  is  the  repeat 
count  for  single  instruction  mode.  This  table  entry  may  be  directly 
modified  and  thus  is  an  alternative  way  of  setting  the 
single-instruction  mode  repeat  count.  In  such  a  case,  ;P  implies  the 
argument  set  in  the  $B  repeat  count  table  rather  than  an  assumed  1. 


8.3.9  Searches 

With  ODT  all  or  any  specified  portion  of  memory  can  be  searched  for 
any  specific  bit  pattern  or  for  references  to  a  particular  location. 
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Word  Search ,  r;W 

Before  initiating  a  word  search,  the  mask  and  search  limits  must  be 
specified.  The  location  represented  by  $M  is  used  to  specify  the  mask 
of  the  search.  $M/  opens  the  mask  register.  The  next  two  sequential 
locations  (opened  by  LINE  FEEDs)  contain  the  lower  and  upper  limits  of 
the  search.  Bits  set  to  1  in  the  mask  are  examined  during  the  search; 
other  bits  are  ignored.  Then  the  search  object  and  the  initiating 
command  are  given  using  the  r;W  command  where  r  is  the  search  object. 
When  a  match  is  found,  (i.e.,  each  bit  set  to  1  in  the  search  object 
is  set  to  1  in  the  word  being  searched  over  the  mask  range)  the 
matching  word  is  printed.  For  example: 

♦$M/9SSQQ8  1774Q0  <LF> 
nnnnnn  ,'000000  1000  <LF> 
nnnnnn  /09090O  1040  <CR> 

*400; W 

001010  Z080779 

001024  ,'900404 

* 

In  the  above  example,  nnnnnn  is  an  address  internal  to  ODT;  this 
location  varies  and  is  meaningful  only  for  reference  purposes.  In  the 
first  line  above,  the  slash  was  used  to  open  $M  which  now  contains 
177400;  the  LINE  FEEDS  opened  the  next  two  sequential  locations  which 
now  contain  the  upper  and  lower  limits  of  the  search. 

In  the  search  process  an  exclusive  OR  (XOR)  is  performed  with  the  word 
currently  being  examined  and  the  search  object,  and  the  result  is 
ANDed  to  the  mask.  If  this  result  is  zero,  a  match  has  been  found  and 
is  reported  on  the  terminal.  Note  that  if  the  mask  is  zero,  all 
locations  within  the  limits  are  printed. 

Typing  CTRL  U  during  a  search  printout  terminates  the  search. 


(test  high-order  eight  bits) 
(set  low  address  limit) 

(set  high  address  limit) 
(initiate  word  search) 


Effective  Address  Search,  r;E 

ODT  provides  a  search  for  words  which  address  a  specified  location. 
Open  the  mask  register  only  to  gain  access  to  the  low  and  high  limit 
registers.  After  specifying  the  search  limits  (as  explained  for  the 
word  search) ,  type  the  command  r;E  (where  r  is  the  effective  address) 
to  initiate  the  search. 


Words  which  are  either  an  absolute  address 
relative  address  offset,  or  a  relative 
address,  are  printed  after  their  addresses. 


(argument  r  itself) ,  a 
branch  to  the  effective 
For  example: 


77490  <LF>  (open  mask  register  only  to  gain 

Tmnnnn  /891000  1010  <LF>  access  to  search  limits) 
nnnnnn/001040  1060  <CR> 


*1024; E 

001016  /001006 

001054  Z002767 

*1020; E 

001022  <''177774 

001020  ,-'001020 


(initiating  search) 
(relative  branch) 
(relative  branch) 
(initiating  a  new  search) 
(relative  address  offset) 
(absolute  address) 
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Particular  attention  should  be  given  to  the  reported  effective  address 
references  because  a  word  may  have  the  specified  bit  pattern  of  an 
effective  address  without  actually  being  so  used,  ODT  reports  all 
possible  references  whether  they  are  actually  used  as  such  or  not. 

Typing  CTRL  U  during  a  search  printout  terminates  the  search. 


8,3.10  The  Constant  Register ,  r;C 

It  is  often  desirable  to  convert  a  relocatable  address  into  its  value 
after  relocation  or  to  convert  a  number  into  its  two’s  complement,  and 
then  to  store  the  converted  value  into  one  or  more  places  in  a 
program.  The  Constant  Register  provides  a  means  of  accomplishing  this 
and  other  useful  functions. 

When  r;C  is  typed,  the  relocatable  expression  r  is  evaluated  to  its 
6-digit  octal  value  and  is  both  printed  on  the  terminal  and  stored  in 
the  Constant  Register.  The  contents  of  the  Constant  Register  may  be 
invoked  in  subsequent  relocatable  expressions  by  typing  the  letter  C, 
Examples  follows 

*-4432;  C=173346  (the  two’s  complement  of  4432  is  placed 

in  the  Constant  Register) 

*6632/062701  C  <CR>  (the  contents  of  the  Constant  Register 

are  stored  in  location  6632) 

*1000; 1R  (relocation  Register  1  is  set  to  1000) 

*1,  4272; C=005272  (relative  location  4272  is  reprinted  as 

an  absolute  location  and  stored  in  the 
Constant  Register) 


8.3.11  Memory  Block  Initialization,  ;F  and  ?I 

The  Constant  Register  can  be  used  in  conjunction  with  the  commands  ?F 
and  ; I  to  set  a  block  of  memory  to  a  given  value.  While  the  most 
common  value  required  is  zero,  other  possibilities  are  plus  one,  minus 
one,  ASCII  space,  etc. 

When  the  command  ;F  is  typed,  ODT  stores  the  contents  of  the  Constant 
Register  in  successive  memory  words  starting  at  the  memory  word 
address  specified  in  the  lower  search  limit,  and  ending  with  the 
address  specified  in  the  upper  search  limit. 

When  the  command  ;I  is  typed,  the  low-order  8  bits  in  the  Constant 
Register  are  stored  in  successive  bytes  of  memory  starting  at  the  byte 
address  specified  in  the  lower  search  limit  and  ending  with  the  byte 
address  specified  in  the  upper  search  limit. 

For  example,  assume  relocation  register  1  contains  7000,  2  contains 
10000,  and  3  contains  15000.  The  following  sequence  sets  word 
locations  7000-7776  to  zero,  and  byte  locations  10000-14777  to  ASCII 
spaces. 
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*$['1/900000  <LF> 
nnnnnn  ,'000900  1.  0  LF> 
nnnnnn  ,-'090080  2,  -2  <LF> 
*0; 0=000000 
*;  F 

*  ♦  M  / 000000  <LF> 
nnnnnn Z007000  2, &  <LF> 
nnnnnn/007776  3,  -1  <CR> 

*40; C=00@040 

*;  I 

* 


(open  mask  register  to  gain  access 
to  search  limits) 

(set  lower  limit  to  7000) 

(set  upper  limit  to  7776) 

(Constant  Register  set  to  zero) 
(Locations  7000-7776  set  to  zero) 


(set  lower  limit  to  10000) 

(set  upper  limit  to  14777) 

(Constant  Register  set  to  40 
(SPACE) ) 

(Byte  locations  10000-14777  are  set 
to  value  in  low-order  8  bits  of 
Constant  Register) 


8.3.12  Calculating  Offsets,  r;0 

Relative  addressing  and  branching  involve  the  use  of  an  offset— the 
number  of  words  or  bytes  forward  or  backward  from  the  current  location 
to  the  effective  address.  During  the  debugging  session  it  may  be 
necessary  to  change  a  relative  address  or  branch  reference  by 
replacing  one  instruction  offset  with  another.  ODT  calculates  the 
offsets  in  response  to  the  r;0  command. 

The  command  r;0  causes  ODT  to  print  the  16-bit  and  8-bit  offsets  from 
the  currently  open  location  to  address  r.  For  example: 

*346/000034  414; 0  806044  622  22  <CR> 

*/ 000022 

In  the  example,  location  346  is  opened  and  the  offsets  from  that 
location  to  location  414  are  calculated  and  printed.  The  contents  of 
location  346  are  then  changed  to  22  (the  8-bit  offset)  and  verified  on 
the  next  line. 

The  8-bit  offset  is  printed  only  if  it  is  in  the  range  -128 (decimal) 
to  127 (decimal)  and  the  16-bit  offset  is  even,  as  was  the  case  above. 
For  example,  the  offset  of  a  relative  branch  is  calculated  and 
modified  as  follows : 


*1634/103421  1034; 0  177776  377  S021  =  377  <CR> 

*/ 103777 

Note  that  the  modified  low-order  byte  377  must  be  combined  with  the 
unmodified  high-order  byte. 


8.3.13  Relocation  Register  Commands,  r;nR,  ;nR,  ;R 

The  use  of  the  relocation  registers  is  defined  in  Section  8.2.  At  the 
beginning  of  a  debugging  session  it  is  desirable  to  preset  the 
registers  to  the  relocation  biases  of  those  relocatable  modules  which 
will  be  receiving  the  most  attention. 

This  can  be  done  by  typing  the  relocation  bias,  followed  by  a 
semicolon  and  the  specification  of  relocation  registers,  as  follows: 
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r;nR 

r  may  be  any  relocatable  expression  and  n  is  an  integer  from  0  to  7. 
If  n  is  omitted  it  is  assumed  to  be  0.  As  an  example: 

*1000; 5R  (puts  1000  into  relocation  register  5) 

*5 1  100;  5R  (effectively  adds  100  to  the  contents 

*  of  relocation  register  5) 

In  certain  uses,  programs  may  be  relocated  to  an  address  below  that  at 
which  they  were  assembled.  This  could  occur  with  PIC  code  (Position 
Independent  Code)  which  is  moved  without  the  use  of  the  Linker.  In 
this  case  the  appropriate  relocation  bias  would  be  the  two's 
complement  of  the  actual  downward  displacement.  One  method  for  easily 
evaluating  the  bias  and  putting  it  in  the  relocation  register  is 
illustrated  in  the  following  example. 

Assume  a  program  was  assembled  at  location  5000  and  was  moved  to 
location  1000.  Then  the  sequence: 

*1000; 1 R 
*1/ -5000; 1 R 

* 

enters  the  two's  complement  of  4000  in  relocation  register  1,  as 
desired. 

Relocation  registers  are  initialized  to  -1,  so  that  unwanted 
relocation  registers  never  enter  into  the  selection  process  when  ODT 
searches  for  the  most  appropriate  register. 

To  set  a  relocation  register  to  -1,  type  ;nR.  To  set  all  relocation 
registers  to  -1,  type  ?R. 

ODT  maintains  a  table  of  relocation  registers,  beginning  at  the 
address  specified  by  $R.  Opening  $R  ($R/)  opens  relocation  register  0. 
Successively  typing  a  line  feed  opens  the  other  relocation  registers 
in  sequence.  When  a  relocation  register  is  opened  in  this  way,  it  may 
be  modified  like  any  other  memory  location. 


8.3.14  The  Relocation  Calculators,  nR  and  ni 

When  a  location  has  been  opened,  it  is  often  desirable  to  relate  the 
relocated  address  and  the  contents  of  the  location  back  to  their 
relocatable  values.  To  calculate  the  relocatable  address  of  the 
opened  location  relative  to  a  particular  relocation  bias,  type  n! , 
where  n  specifies  the  relocation  register.  This  calculator  works  with 
opened  bytes  and  words.  If  n  is  omitted,  the  relocation  register 
whose  contents  are  closest  but  less  than  or  equal  to  the  opened 
location  is  selected  automatically  by  ODT.  In  the  following  example, 
assume  that  these  conditions  are  fulfilled  by  relocation  register  2, 
which  contains  2000.  To  find  the  most  likely  module  that  a  given 
opened  byte  is  in: 

*2508 S 011  =  !=2, 000500 

Typing  nR  after  opening  a  word  causes  ODT  to  print  the  octal  number 
which  equals  the  value  of  the  contents  of  the  opened  location  minus 
the  contents  of  relocation  register  n.  If  n  is  omitted,  ODT  selects 
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the  relocation  register  whose  contents  are  closest  but  less  than  or 
equal  to  the  contents  of  the  opened  location.  For  example,  assume  the 
relocation  bias  stored  in  relocation  register  1  is  7000;  then: 

*1, 509/060000  1R  =  1. 171600 

The  value  171000  is  the  content  of  1,500,  relative  to  the  base  7000, 
An  example  of  the  use  of  both  relocation  calculators  follows. 

If  relocation  register  1  contains  1000,  and  relocation  register  2 
contains  2000,  then  to  calculate  the  relocatable  addresses  of  location 
3000  and  its  contents,  relative  to  1000  and  2000,  the  following  can  be 
performed, 

*3909/800416  1  !  =1/ 062000  2 1=2.001000  1R=1. 177416  2R  =  2. 176416 


8.3.15  ODT  Priority  Level,  $P 

$P  represents  a  location  in  ODT  that  contains  the  interrupt  (or 
processor)  priority  level  at  which  ODT  operates.  If  $P  contains  the 
value  377,  ODT  operates  at  the  priority  level  of  the  processor  at  the 
time  ODT  is  entered.  Otherwise  $P  may  contain  a  value  between  0  and  7 
corresponding  to  the  fixed  priority  at  which  ODT  operates. 

To  set  ODT  to  the  desired  priority  level,  open  $P.  ODT  prints  the 
present  contents,  which  may  then  be  changed: 

♦♦P/000006  377  <CR> 

* 

If  $P  is  not  specified,  its  value  is  seven. 

ODT  priority  must  be  set  to  0  if  ODT  is  being  used  in  an  F/B 
environment  with  another  job  running. 

Breakpoints  may  be  set  in  routines  which  run  at  different  priority 
levels.  For  example,  a  program  running  at  a  low  priority  may  use  a 
device  service  routine  which  operates  at  a  higher  priority  level.  If 
a  breakpoint  occurs  from  a  low-priority  routine,  ODT  operates  at  a  low 
priority?  if  an  interrupt  occurs  from  a  high  priority  routine,  the 
breakpoints  in  the  high  priority  routine  will  not  be  recognized  since 
they  were  removed  when  the  low  priority  breakpoint  occurred.  That  is, 
interrupts  set  at  a  priority  higher  than  the  one  at  which  ODT  is 
running  will  occur  and  any  breakpoints  will  not  be  recognized.  ODT 
disables  all  breakpoints  from  the  program  whenever  it  gains  control. 
Breakpoints  are  enabled  when  ?P  and  ?G  commands  are  executed.  For 
example : 

*  $  P  /  6  6  G  6  0  7  5 
*1000; B 
*2006; B 
*1600; G 

60; 001060 

*  (an  interrupt  occurs  and  is  serviced) 

If  a  higher  level  interrupt  occurs  while  ODT  is  waiting  for  input  the 
interrupt  will  be  serviced,  and  no  breakpoints  will  be  recognized. 
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8.3.16  ASCII  Input  and  Output ,  r;nA 

ASCII  text  may  be  inspected  and  changed  by  the  command: 

r;nA 

where  r  is  a  relocatable  expression ,  and  n  is  a  character  count.  If  n 
is  omitted  it  is  assumed  to  be  1.  ODT  prints  n  characters  starting  at 
location  r,  followed  by  a  carriage  return/line  feed.  Type  one  of  the 
following: 

<CR>  ODT  outputs  a  carriage  return/line  feed  and 

an  asterisk  and  waits  for  another  command. 

<LF>  ODT  opens  the  byte  following  the  last  byte 

output. 

Up  to  n  characters  of  text 

ODT  inserts  the  text  into  memory ,  starting  at 
location  r.  If  fewer  than  n  characters  are 
typed,  terminate  the  command  by  typing 
CTRL  U,  causing  a  carriage  return/line 
feed/asterisk  to  be  output.  However,  if 
exactly  n  characters  are  typed,  ODT  responds 
with  a  carriage  return/line  feed,  the  address 
of  the  next  available  byte  and  a  carriage 
return/line  feed/asterisk. 

ODT  does  not  check  the  magnitude  of  n. 


8.4  PROGRAMMING  CONSIDERATIONS 

Information  in  this  section  is  not  necessary  for  the  efficient  use  of 
ODT.  However,  it  does  provide  a  better  understanding  of  how  ODT 
performs  some  of  its  functions  and  in  certain  difficult  debugging 
situations,  this  understanding  is  necessary. 


8.4.1  Functional  Organization 

The  internal  organization  of  ODT  is  almost  totally  modularized  into 
independent  subroutines.  The  internal  structure  consists  of  three 
major  functions:  command  decoding,  command  execution,  and  various 
utility  routines. 

The  command  decoder  interprets  the  individual  commands,  checks  for 
command  errors,  saves  input  parameters  for  use  in  command  execution, 
and  sends  control  to  the  appropriate  command  execution  routine. 

The  command  execution  routines  take  parameters  saved  by  the  command 
decoder  and  use  the  utility  routines  to  execute  the  specified  command. 
Command  execution  routines  exit  either  to  the  object  program  or  back 
to  the  command  decoder. 

The  utility  routines  are  common  routines  such  as  SAVE-RESTORE  and  I/O. 
They  are  used  by  both  the  command  decoder  and  the  command  executers. 
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8.4.2  Breakpoints 

The  function  of  a  breakpoint  is  to  give  control  to  ODT  whenever  the 
user  program  tries  to  execute  the  instruction  at  the  selected  address. 
Upon  encountering  a  breakpoint,  all  of  the  ODT  commands  can  be  used  to 
examine  and  modify  the  program. 

When  a  breakpoint  is  executed,  ODT  removes  all  the  breakpoint 
instructions  from  the  user's  code  so  that  the  locations  may  be 
examined  and/or  altered.  ODT  then  types  a  message  on  the  terminal  of 
the  form  Bn;k  where  k  is  the  breakpoint  address  (and  n  is  the 
breakpoint  number) .  The  breakpoints  are  automatically  restored  when 
execution  is  resumed. 

A  major  restriction  in  the  use  of  breakpoints  is  that  the  word  where  a 
breakpoint  was  set  must  not  be  referenced  by  the  program  in  any  way 
since  ODT  altered  the  word.  Also,  no  breakpoint  should  be  set  at  the 
location  of  any  instruction  that  clears  the  T-bit.  For  example: 

MOV  #240,177776  ;SET  PRIORITY  TO  LEVEL  5 


NOTE 

Instructions  that  cause  or  return  from 
traps  (e.g.,  EMT,  RTI)  are  likely  to 
clear  the  T-bit,  since  a  new  word  from 
the  trap  vector  or  the  stack  is  loaded 
into  the  Status  Register. 


A  breakpoint  occurs  when  a  trace  trap  instruction  (placed  in  the  user 
program  by  ODT)  is  executed.  When  a  breakpoint  occurs,  the  following 
steps  are  taken: 

1.  Set  processor  priority  to  seven  (automatically  set  by  trap 
instruction) . 

2.  Save  registers  and  set  up  stack. 

3.  If  internal  T-bit  trap  flag  is  set,  go  to  step  13. 

4 .  Remove  breakpoints . 

5.  Reset  processor  priority  to  ODT's  priority  or  user's 
priority. 

6.  Make  sure  a  breakpoint  or  single-instruction  mode  caused  the 
interrupt. 

7.  If  the  breakpoint  did  not  cause  the  interrupt,  go  to  step  15. 

8.  Decrement  repeat  count. 

9.  Go  to  step  18  if  non-zero;  otherwise  reset  count  to  one. 

10.  Save  terminal  status. 

11.  Type  message  about  the  breakpoint  or  single-instruction  mode 
interrupt. 
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12.  Go  to  command  decoder. 

13.  Clear  T-bit  in  stack  and  internal  T-bit  flag. 

14.  Jump  to  the  Go  processor. 

15.  Save  terminal  status. 

16.  Type  BE  (Bad  Entry)  followed  by  the  address. 

17.  Clear  the  T-bit,  if  set,  in  the  user  status  and  proceed  to 
the  command  decoder. 

18.  Go  to  the  Proceed  processor,  bypassing  the  TT  restore 
routine. 

Note  that  steps  1-5  inclusive  take  approximately  100  microseconds 
during  which  time  interrupts  are  not  permitted  (ODT  is  running  at 
level  7) • 

When  a  proceed  (?P)  command  is  given,  the  following  occurs: 

1.  The  proceed  is  checked  for  legality. 

2.  The  processor  priority  is  set  to  seven. 

3.  The  T-bit  flags  (internal  and  user  status)  are  set. 

4.  The  user  registers,  status,  and  Program  Counter  are  restored. 

5.  Control  is  returned  to  the  user. 

6.  When  the  T-bit  trap  occurs,  steps  1,  2,  3,  13,  and  14  of  the 
breakpoint  sequence  are  executed,  breakpoints  are  restored, 
and  program  execution  resumes  normally. 

When  a  breakpoint  is  placed  on  an  IOT,  EMT,  TRAP,  or  any  instruction 
causing  a  trap,  the  following  occurs: 

1.  When  the  breakpoint  occurs  as  described  above,  ODT  is 
entered. 

2.  When  ;P  is  typed,  the  T-bit  is  set  and  the  IOT,  EMT,  TRAP,  or 
other  trapping  instruction  is  executed. 

3.  This  causes  the  current  PC  and  status  (with  the  T-bit 
included)  to  be  pushed  on  the  stack. 

4.  The  new  PC  and  status  (no  T-bit  set)  are  obtained  from  the 
respective  trap  vector. 

5.  The  whole  trap  service  routine  is  executed  without  any 
breakpoints. 

6.  When  an  RTI  is  executed,  the  saved  PC  and  PS  (including  the 
T-bit)  are  restored.  The  instruction  following  the 
trap-causing  instruction  is  executed.  If  this  instruction  is 
not  another  trap-causing  instruction,  the  T-bit  trap  occurs, 
causing  the  breakpoints  to  be  reinserted  in  the  user  program. 
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or  the  single-instruction  mode  repeat  count  to  be 
decremented.  If  the  following  instruction  is  a  trap-causing 
instruction,  this  sequence  is  repeated  starting  at  step  3. 


NOTE 

Exit  from  the  trap  handler  must  be  via 
the  RTI  instruction.  Otherwise,  the 
T-bit  is  lost.  ODT  can  not  regain 
control  since  the  breakpoints  have  not 
been  reinserted  yet. 


Note  that  the  ;P  command  is  illegal  if  a  breakpoint  has  not  occurred 
(ODT  responds  with  ?) ;  ;P  is  legal,  however,  after  any  trace  trap 
entry. 

The  internal  breakpoint  status  words  have  the  following  formats 

1.  The  first  eight  words  contain  the  breakpoint  addresses  for 
breakpoints  0-7.  (The  ninth  word  contains  the  address  of  the 
next  instruction  to  be  executed  in  single-instruction  mode.) 

2.  The  next  eight  words  contain  the  respective  repeat  counts. 
The  following  word  contains  the  repeat  count  for 
single-instruction  mode.) 

These  words  may  be  changed  at  will,  either  by  using  the  breakpoint 
commands  or  by  direct  manipulation  with  $B. 

When  program  runaway  occurs  (that  is,  when  the  program  is  no  longer 
under  ODT  control,  perhaps  executing  an  unexpected  part  of  the  program 
where  a  breakpoint  has  not  been  placed) ,  ODT  may  be  given  control  by 
pressing  the  HALT  key  to  stop  the  computer, and  restarting  ODT  (see 
Section  8.1).  ODT  prints  *,  indicating  that  it  is  ready  to  accept  a 
command. 

If  the  program  being  debugged  uses  the  teleprinter  for  input  or 
output,  the  program  may  interact  with  ODT  to  cause  an  error  since  ODT 
uses  the  teleprinter  as  well.  This  interactive  error  will  not  occur 
when  the  program  being  debugged  is  run  without  ODT. 

Note  the  following  rules  concerning  the  ODT  break  routine: 

1.  If  the  teleprinter  interrupt  is  enabled  upon  entry  to  the  ODT 
break  routine,  and  no  output  interrupt  is  pending  when  ODT  is 
entered,  ODT  generates  an  unexpected  interrupt  when  returning 
control  to  the  program. 

2.  If  the  interrupt  of  the  teleprinter  reader  (the  keyboard)  is 
enabled  upon  entry  to  the  ODT  break  routine,  and  the  program 
is  expecting  to  receive  an  interrupt  to  input  a  character, 
both  the  expected  interrupt  and  the  character  are  lost. 

3.  If  the  teleprinter  reader  (keyboard)  has  just  read  a 
character  into  the  reader  data  buffer  when  the  ODT  break 
routine  is  entered,  the  expected  character  in  the  reader  data 
buffer  is  lost. 
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8*4*3  Searches 

The  word  search  allows  the  user  to  search  for  bit  patterns  in 
specified  sections  of  memory.  Using  the  $M/  command ,  the  user 
specifies  a  mask,  a  lower  search  limit  ($M+2),  and  an  upper  search 
limit  ($M+4).  The  search  object  is  specified  in  the  search  command 
itself. 

The  word  search  compares  selected  bits  (where  ones  appear  in  the  mask) 
in  the  word  and  search  object.  If  all  of  the  selected  bits  are  equal, 
the  unmasked  word  is  printed. 

The  search  algorithm  is : 

1.  Fetch  a  word  at  the  current  address. 

2.  XOR  (exclusive  OR)  the  word  and  search  object. 

3.  AND  the  result  of  step  2  with  the  mask. 

4.  If  the  result  of  step  3  is  zero,  type  the  address  of  the 
unmasked  word  and  its  contents.  Otherwise,  proceed  to  step 

5. 

5.  Add  two  to  the  current  address.  If  the  current  address  is 
greater  than  the  upper  limit,  type  *  and  return  to  the 
command  decoder,  otherwise  go  to  step  1. 

Note  that  if  the  mask  is  zero,  ODT  prints  every  word  between  the 
limits,  since  a  match  occurs  every  time  (i.e.,  the  result  of  step  3  is 
always  zero) • 

In  the  effective  address  search,  ODT  interprets  every  word  in  the 
search  range  as  an  instruction  which  is  interrogated  for  a  possible 
direct  relationship  to  the  search  object.  The  mask  register  is  opened 
only  to  gain  access  to  the  search  limit  registers. 

The  algorithm  for  the  effective  address  search  is  (where  (X)  denotes 
contents  of  X,  and  K  denotes  the  search  object) : 

1.  Fetch  a  word  at  the  current  address  X. 

2.  If  (X)=K  [direct  reference],  print  contents  and  go  to  step  5. 

3.  If  (X) +X+2=K  [indexed  by  PC],  print  contents  and  go  to  step 

5. 

4.  If  (X)  is  a  relative  branch  to  K,  print  contents. 

5.  Add  two  to  the  current  address.  If  the  current  address  is 
greater  than  the  upper  limit,  perform  a  carriage  return/line 
feed  and  return  to  the  command  decoder;  otherwise,  go  to 
step  1. 


8.4.4  Terminal  Interrupt 

Upon  entering  the  TT  SAVE  routine,  the  following  occurs: 
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1.  Save  the  LSR  status  register  (TKS) . 

2.  Clear  interrupt  enable  and  maintenance  bits  in  the  TKS. 

3.  Save  the  TT  status  register  (TPS) . 

4.  Clear  interrupt  enable  and  maintenance  bits  in  the  TPS. 
To  restore  the  TT: 

1.  Wait  for  completion  of  any  I/O  from  ODT. 

2.  Restore  the  TKS. 

3.  Restore  the  TPS. 


NOTES 

If  the  TT  printer  interrupt  is  enabled 
upon  entry  to  the  ODT  break  routine,  the 
following  may  occur: 

1.  If  no  output  interrupt  is 
pending  when  ODT  is  entered,  an 
additional  interrupt  always 
occurs  when  ODT  returns  control 
to  the  user. 

2.  If  an  output  interrupt  is 
pending  upon  entry,  the 
expected  interrupt  occurs  when 
the  user  regains  control. 

If  the  TT  reader  (keyboard)  is  busy  or 
done,  the  expected  character  in  the 
reader  data  buffer  is  lost. 

If  the  TT  reader  (keyboard)  interrupt  is 
enabled  upon  entry  to  the  ODT  break 
routine,  and  a  character  is  pending,  the 
interrupt  (as  well  as  the  character)  is 
lost. 


8 . 5  ERROR  DETECTION 

ODT  detects  two  types  of  error:  illegal  or  unrecognizable  command  and 
bad  breakpoint  entry.  ODT  does  not  check  for  the  legality  of  an 
address  when  commanded  to  open  a  location  for  examination  or 
modification.  Thus  the  command: 


*17? 774/ 

7H-TRRP  TO  4  683362 

references  nonexistent  memory,  thereby  causing  a  trap  through  the 
vector  at  location  4.  If  this  vector  has  not  been  properly 
initialized,  unpredictable  results  occur. 
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Typing  something  other  than  a  legal  command  causes  ODT  to  ignore  the 
command,  prints 

(echoes  illegal  command) ? 

* 

and  wait  for  another  command.  Therefore,  to  cause  ODT  to  ignore  a 
command  just  typed,  type  any  illegal  character  (such  as  9  or  RUBOUT) 
and  the  command  will  be  treated  as  an  error,  i.e.,  ignored. 

ODT  suspends  program  execution  whenever  it  encounters  a  breakpoint, 
i.e.,  traps  to  its  breakpoint  routine.  If  the  breakpoint  routine  is 
entered  and  no  known  breakpoint  caused  the  entry,  ODT  prints: 

BEnnnnnn 

* 

and  waits  for  another  command.  BEnnnnnn  denotes  Bad  Entry  from 
location  nnnnnn.  A  bad  entry  may  be  caused  by  an  illegal  trace  trap 
instruction,  setting  the  T-bit  in  the  status  register,  or  by  a  jump  to 
the  middle  of  ODT. 
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PROGRAMMED  REQUESTS 


A  number  of  services  at  the  machine  language  level  which  the  monitor 
regularly  provides  to  system  programs  are  also  available  to 
user-written  programs.  These  include  services  for  file  manipulation, 
command  interpretation,  and  facilities  for  input  and  output 
operations.  User  programs  call  these  monitor  services  by  means  of 
"programmed  requests",  which  are  assembler  macro  calls  written  into 
the  user  program  and  interpreted  by  the  monitor  at  program  execution 
time. 


NOTE 

Programmed  requests  used  in  Version  2 
differ  from  those  used  in  Version  1;  for 
example,  the  channel  number  in  Version  1 
was  limited  to  the  range  0-17,  where  it 
is  not  in  Version  2;  blank  fields  in 
macro  calls  were  not  allowed  in  Version 
1,  and  are  in  Version  2;  a  .area 
argument  points  to  an  argument  list  in 
Version  2,  where  arguments  were  pushed 
on  the  stack  in  Version  1. 

Although  programs  written  for  use  under 
Version  1  will  assemble  and  execute 
properly,  it  is  to  the  user's  advantage 
to  convert  these  programs  so  they  use 
the  new  Version  2  macro  calls  wherever 
possible.  Only  macro  calls  which  are 
used  with  the  current  version  of  RT-11 
(Version  2)  are  discussed  in  this 
chapter.  See  Section  9.5  for 
instructions  on  converting  Version  1 
macro  calls  to  the  Version  2  format. 


The  macro  definitions  for  both  Version  1  and  Version  2  requests  are 
included  in  the  file  SYSMAC.SML  (in  8K  systems,  the  system  macro 
library  is  called  SYSMAC.8K);  Appendix  D  provides  a  listing  of 
SYSMAC.SML.  Refer  to  Chapter  5  for  general  information  related  to  the 
use  of  macro  calls. 
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9.1  FORMAT  OF  A  PROGRAMMED  REQUEST 

The  basis  of  a  programmed  request  is  the  EMT  instruction,  used  to 
communicate  information  to  the  monitor.  When  an  EMT  is  executed, 
control  is  passed  to  the  monitor,  which  extracts  appropriate 
information  from  the  EMT  and  executes  the  function  required.  The 
low-order  byte  of  the  EMT  instruction  contains  a  code  which  is 
interpreted  as: 


Low-Order  Byte 
of  EMT 

377 


Meaning 

Reserved;  RT-11  ignores  this  EMT  and 
control  to  the  user  program  immediately. 


returns 


376 

375 

374 

360-373 

340-357 

0-337 


Used  internally  by  the  RT-11  monitor;  this 
code  should  never  be  used  by  user  programs. 


EMT 


R0 


Programmed  request  with  several  arguments:  m» 
must  point  to  a  list  of  arguments  which  designates 
the  specific  function. 

Programmed  request  with  one  argument:  R0  contains 
a  function  code  in  the  high-order  byte  and  a 
channel  number  (see  Section  9.2.1)  or  0  in  the 
low-order  byte. 

Used  internally  by  the  RT-11  monitor;  these  EMT 
codes  should  never  be  used  by  user  programs. 


Programmed  request  with 
and/or  in  R0. 


arguments  on  the  stack 


Version  1  programmed  request.  These  EMTs  use 
arguments  both  on  the  stack  and  in  R0.  They  are 
supported  for  binary  compatability  with  Version  1 
programs . 

A  programmed  request  consists  of  a  macro  call  followed,  where 
necessary,  by  one  or  more  arguments.  Arguments  supplied  to  a  macro 
call  must  be  legal  assembler  expressions  since  arguments  will  be  used 
as  source  fields  in  MOV  instructions  when  the  macros  are  expanded  at 
assembly  time.  The  following  two  formats  are  used: 


1.  PRGREQ  ARG1 , ARG2 , . . . ARGN 

2.  PRGREQ  AREA, ARG1 , ARG2 , . . . ARGN 

Form  1  above  contains  the  arguments  ARG1  through  ARGN;  no  argument 
list  pointer  is  required.  Macros  of  this  form  generate  either  an  EMT 
374  or  one  of  the  EMTs  340-357.  Certain  arguments  for  this  form  may  be 
omitted,  and  these  are  described  later  in  this  chapter  under  the 
appropriate  macro  description. 

In  form  2  above,  AREA  is  a  pointer  to  the  argument  list  which  contains 
the  arguments  ARG1  through  ARGN.  This  form  always  causes  an  EMT  375 
to  be  generated.  Blank  fields  are  permitted;  however,  if  the  AREA 
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argument  is  blank,  the  monitor  assumes  that  RO  points  to  a  valid 
argument  block  (see  Section  9.2.3).  If  any  of  the  fields  ARG1  to  ARGN 
are  blank,  the  corresponding  entries  in  the  argument  list  are  left 
untouched .  Thus , 

. PRGREQ  AREA,A1,A2 

points  RO  to  the  argument  block  at  AREA  and  fills  in  the  first  and 
second  arguments,  while: 

.PRGREQ  AREA 

points  RO  to  the  block,  and  fills  in  the  first  word  but  does  not  fill 
in  any  other  arguments.  The  call: 

.PRGREQ  ,A1 

assumes  RO  points  to  the  argument  block  and  fills  in  the  A1  argument, 
but  leaves  the  A2  argument  alone.  The  call: 

.PRGREQ 

generates  only  an  EMT  375  and  assumes  that  both  RO  and  the  block  to 
which  it  points  are  properly  set  up. 

The  arguments  to  RT-11  programmed  request  macros  all  serve  as  the 
source  field  of  a  MOV  instruction  which  moves  a  value  into  the 
argument  block  or  RO.  For  example: 

.PRGREQ  CHAR 

expands  into: 

MOV  CHAR,R0 
EMT  357 

Care  should  be  taken  to  make  certain  that  the  arguments  specified  are 
legal  source  fields  and  that  the  address  accurately  represents  the 
value  desired.  If  the  value  is  a  constant,  immediate  mode  [#]  should 
be  used;  if  the  value  is  in  a  register,  the  register  mnemonic  [Rn] 
should  be  used;  if  the  value  is  indirectly  addressed,  the  appropriate 
register  convention  is  necessary  [@Rn] ,  and  if  the  value  is  in  memory, 
the  label  of  the  location  whose  value  is  the  argument  is  used. 

Following  are  some  examples  of  both  correct  and  incorrect  macro  calls. 
Consider  the  general  request: 

. PRGREQ  . AREA , . ARG1 , . . . ARGN 

A  more  common  way  of  writing  a  request  of  this  form  is: 

. PRGREQ  # ARE A , # ARG1 , . . . # ARGN 

In  this  format,  the  address  of  AREA  is  put  directly  into  the  argument 
list.  AREA  is  the  tag  which  indicates  the  beginning  of  the  argument 
block.  For  example: 

.PRGREQ  # AREA, #4 


AREA: 


. BLKW  3 
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When  a  direct  numerical  argument  is  required,  the  #  causes  the  correct 
value  to  be  put  into  the  argument  block..  For  example: 

. PRGREQ  #AREA, #4 

is  correct,  while: 

.PRGREQ  # AREA, 4 

is  not.  This  form  interprets  the  4  as  meaning  "move  the  contents  of 
location  4  into  the  argument  block",  where  the  number  4  itself  should 
be  moved  into  the  block. 

If  the  request  is  written  as: 

.PRGREQ  AREA, #4 

it  is  interpreted  as  "use  the  contents  of  location  AREA  as  the  list 
pointer”,  when  the  address  of  AREA  is  actually  desired.  This 
expansion  could  be  used  with  the  following  form: 

.PRGREQ  LIST1, #4 


LIST1 :  AREA 
AREA:  .BLKW3 

In  this  case,  the  content  of  location  LIST1  is  the  address  of  the 
argument  list.  Similarly,  this  form  is  correct: 

.PRGREQ  LIST1, NUMBER 
LIST1:  AREA 

NUMBER:  4 

In  this  case,  the  contents  of  the  locations  LIST1  and  NUMBER  are  the 
argument  list  pointer  and  data  value,  respectively. 


NOTE 

All  registers  except  RO  are  preserved 
across  a  programmed  request.  (In 
certain  cases,  RO  may  contain 
information  passed  back  by  the  monitor; 
however,  unless  the  description  of  a 
request  indicates  that  a  specific  value 
is  returned  in  RO,  it  may  be  assumed 
that  the  contents  of  RO  are 
unpredictable  upon  return  from  the 
request) .  With  the  exception  of  calls  to 
the  CSI ,  the  position  of  the  stack 
pointer  is  also  preserved  across  a 
programmed  request. 
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9.2  SYSTEM  CONCEPTS 

Some  basic  operational  characteristics  and  concepts  of  RT-11  are 
described  below. 


9.2.1  Channel  Number  (chan) 

A  channel  number  is  a  logical  identifier  in  the  range  0  to  377 (octal) 
for  a  file  or  "set  of  data"  used  by  the  RT-11  monitor.  Thus,  when  a 
file  is  opened  on  a  particular  device,  a  channel  number  is  assigned  to 
that  file.  To  refer  to  an  open  file,  it  is  only  necessary  to  refer  to 
the  appropriate  channel  number  for  that  file. 


9.2.2  Device  block  (dblk) 

A  device  block  is  a  four-word  block  of  radix-50  information  which 
specifies  a  physical  device  and  file  name  for  an  RT-11  programmed 
request.  (Refer  to  Chapter  5  for  an  explanation  of  .RAD50  strings.) 
For  example,  a  device  block  representing  a  file  FILE. EXT  on  device  DK: 
could  be  written  as: 

. RAD50  /DK  / 

. RAD50  /FIL/ 

•RAD50  /E  / 

. RAD50  /EXT/ 

The  first  word  contains  the  device  name,  the  second  and  third  words 
contain  the  file  name,  and  the  fourth  contains  the  extension.  Device, 
name,  and  extension  must  each  be  left- justified  in  the  appropriate 
field.  This  string  could  also  be  written  as: 

.RAD50  /DK  FILE  EXT/ 

Note  that  spaces  must  be  used  to  fill  out  each  field.  Note  also  that 
the  colon  and  period  separators  do  not  appear  in  the  actual  RAD 50 
string.  They  are  used  only  by  the  monitor  keyboard  interface  to 
delimit  the  various  fields. 


9.2.3  EMT  Argument  Blocks 

Programmed  requests  which  call  the  monitor  via  EMT  375  use  R0  as  a 
pointer  to*  an  argument  list.  In  general,  this  argument  list  appears 
as  follows: 


address 

contents 

Function  Channel 

X 

Code  Number 

x+2 

argumentl 

x+4 

argument2 
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RO  points  to  location  x.  The  even  (low-order)  byte  of  location  x 
contains  the  channel  number  named  in  the  macro  call.  If  no  channel 
number  is  required,  the  byte  is  set  to  0.  The  odd  (high-order)  byte  of 
x  is  a  code  specifying  the  function  to  be  performed.  Locations  x+2, 
x+4,  etc.  contain  arguments  to  be  interpreted.  These  are  described 
in  detail  under  each  request. 

Requests  which  use  EMT  374  set  up  RO  with  the  channel  number  in  the 
even  byte  and  the  function  code  in  the  odd  byte.  They  require  no 
other  arguments. 


9.2.4  Important  Memory  Areas 


9. 2. 4.1  Vector  Addresses  (0-37,  60-477)  -  Certain  areas  of  memory 
between  0  and  477  are  reserved  for  use  by  RT-11.  KMON  does  not  load 
these  locations  from  the  save  image  file  when  it  initiates  a  program, 
i.e.,  R,  RUN,  and  GET  will  not  load  these  words.  However,  no  hardware 
memory  protection  is  supplied.  Thus,  programs  should  never  alter  the 
contents  of  the  indicated  areas  at  run-time. 


Locations 


Contents 


0,2 

Monitor  restart.  Executes  .EXIT 

returns  control  to  KMON. 

request 

and 

4,6  # 

Time  out  or  bus  error  trap;  RT-11 
point  to  its  internal  trap  handler. 

sets 

this 

to 

10,12 

Reserved  instruction  trap;  RT-11 

point  to  its  internal  trap  handler. 

sets 

this 

to 

30,32 

EMT  trap  vector  and  status. 

40-57  RT-11  system  communication  area  (see  below) . 

60,62  TTY  input  interrupt  vector  and  status. 

64,66  TTY  output  interrupt  vector  and  status. 

100,102  KW11L  vector  and  status. 

204,206  RF11  vector  and  status. 

214,216  TC11  vector  and  status. 

220,222  RK05  vector  and  status. 

330,332  GT40  shift  out  interrupt  vector  and  status. 

These  areas  are  not  replaced  by  RT-11.  If  they  are  destroyed  by  a 
program,  the  system  must  be  re-bootstrapped,  or  the  program  must 
restore  them. 
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9. 2. 4. 2  Resident  Monitor  -  Section  2.4  of  Chapter  2  describes  the 
placement  of  monitor  components  when  either  the  Single- Job  Monitor  or 
F/B  Monitor  is  brought  into  memory;  included  is  the  approximate  size 
of  each  monitor  component  and  the  size  of  the  area  available  for 
handlers  and  user  programs. 


9. 2. 4. 3  System  Communication  Area  -  RT-11  uses  bytes  40-57  to  hold 
information  about  the  program  currently  executing,  as  well  as  certain 
information  used  only  by  the  monitor.  A  description  of  these  bytes 
follows ; 


Bytes 

40,41 


42,43 


44,45 


Meaning  and  Use 


Start  address  of  job.  When  a  file  is  linked  into 
an  RT-11  memory  image,  this  word  is  set  to  the 
starting  address  of  the  job  either  with  the  Linker 
/T  switch  or  as  an  argument  in  the  .END  statement 
of  the  program.  When  a  foreground  program  is 
executed,  the  FRUN  processor  relocates  this  word 
to  contain  the  actual  starting  address  of  the 
program. 

Initial  value  of  the  stack  pointer.  If  it  is  not 
set  by  the  user  program  in  an  .ASECT,  it  defaults 
to  1000  or  the  top  of  the  .ASECT  in  the 
background,  whichever  is  larger.  If  a  foreground 
program  does  not  specify  a  stack  pointer  in  this 
word,  a  default  stack  (128  decimal  words)  is 
allocated  by  FRUN  immediately  below  the  program. 
The  initial  stack  pointer  can  also  be  set  with  the 
Linker  /M  switch  option. 

Job  Status  Word.  Used  as  a  flag  word  for  the 
monitor.  Certain  bits  are  maintained  by  the 
monitor  exclusively  while  others  must  be  set  or 
cleared  by  the  user  job.  Those  bits  in  the 
following  list  which  are  marked  by  an  asterisk  are 
bits  which  must  be  set  by  the  user  job. 


Since  the  currently  unassigned  bits  may  be  used  in 
future  releases  of  RT-11,  user  programs  should  not 
use  these  bits  for  internal  flags. 

Bit 

Number  Meaning 

15  USR  swap  bit.  (Unused  in  F/B.)  Programs 

which  do  not  require  the  USR  to  be 
swapped  have  this  bit  set.  See  the 
Swapping  Algorithm  (Section  9.2.5)  for 
more  details. 

14  Unused. 


*13  Reenter  bit.  When  set,  this  bit 

indicates  that  the  program  may  be 
restarted  from  the  terminal  with  the 
REENTER  command. 
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*12  Special  mode  TT  bit.  When  set,  this  bit 

indicates  that  the  job  is  in  a  "special" 
keyboard  mode  of  input.  Refer  to  the 
explanation  of  the  .TTYIN/ .TTINR 
requests  for  details. 

11-10  For  F/B  Monitor  use  only. 

9  Overlay  Bit.  Set  (by  the  Linker)  if  the 

job  uses  the  Linker  overlay  structure. 

8  CHAIN  bit.  If  this  bit  is  set  in  a 

job's  save  image,  words  500-776  are 
loaded  from  the  save  file  when  the  job 
is  started  even  if  the  job  is  entered 
via  CHAIN.  (These  words  are  normally 
used  to  pass  parameters  across  CHAINS.) 
The  bit  is  set  when  a  job  is  running  if 
and  only  if  the  job  was  actually  entered 
with  CHAIN. 

*7  Error  halt  bit.  When  set,  this  bit 

indicates  a  halt  on  an  I/O  error.  If 
the  user  desires  to  halt  when  any  I/O 
device  error  occurs,  this  bit  should  be 
set.  (Unused  in  F/B.) 

*6  Inhibit  TT  wait  bit.  For  use  with  the 

Foreground/Background  system.  When  set, 
this  bit  inhibits  the  monitor  from 
entering  a  console  terminal  wait  state. 
Refer  to  the  sections  concerning 
.TTYIN/. TTINR,  and  .TTYOUT/ .TTOUTR  for 
more  information. 

5-0  Unused. 

46,47  USR  load  address.  Normally  0,  this  word  may  be 

set  to  any  valid  word  address  in  the  user's 
program.  See  Section  9.2.5,  Swapping  Algorithm, 
for  details  of  use. 

50,51  High  memory  address.  The  monitor  maintains  the 
highest  address  the  user  program  can  use  in  this 
word.  The  Linker  sets  it  initially.  It  is 
modified  only  via  the  .SETTOP  (Set  Top  of  Memory) 
monitor  request. 

52  EMT  error  code.  If  a  monitor  request  results  in 

an  error,  the  code  number  of  the  error  is  always 
returned  in  byte  52.  Each  monitor  call  has  its  own 
set  of  possible  errors.  It  is  recommended  that 
the  user  program  reference  byte  52  with  absolute 
addressing,  rather  them  relative  addressing.  For 
example: 

ERRWRD  =  52 

TSTB  ERRWRD  ; RELATIVE  ADDRESSING 

TSTB  @#ERRWRD  ; ABSOLUTE  ADDRESSING 
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Location  52  should  always  be  addressed  as  a  byte, 
never  as  a  word,  since  byte  53  may  be  used  in 
future  releases  of  RT-11. 

53  Reserved  for  future  system  use. 

54,55  Address  of  the  beginning  of  the  Resident  Monitor. 

RT-11  always  loads  the  resident  into  the  highest 
available  memory  locations;  this  word  points  to 
its  first  location.  It  must  never  be  altered  by 
the  user.  Doing  so  will  cause  RT-11  to 
malfunction. 

56  Fill  character  (7-bit  ASCII) .  Some  high-speed 
terminals  require  filler  (null)  characters  after 
printing  certain  characters.  Byte  56  should 
contain  the  ASCII  7-bit  representation  of  the 
character  after  which  fillers  are  required. 

57  Fill  count.  This  byte  specifies  the  number  of 
fill  characters  required.  If  bytes  56  and  57*0, 
no  fillers  are  required. 

The  required  fill  characters  ares 

Value  of 

Terminal  No.  of  fills  Word  56 


Serial 

LA30 

0 

300 

baud 

10 

after 

carriage  return 

5015 

Serial 

LA30 

0 

150 

baud 

4 

after 

carriage  return 

2015 

Serial 

LA30 

0 

110 

baud 

2 

after 

carriage  return 

1015 

VT05 

0 

2400 

baud 

4 

after 

line  feed 

2012 

VT05 

0 

1200 

baud 

2 

after 

line  feed 

1012 

VT05 

0 

600 

baud 

1 

after 

line  feed 

412 

9.2.5  Swapping  Algorithm 

Programmed  requests  are  divided  into  two  categories  according  to 
whether  or  not  they  require  the  USR  to  be  in  memory  (see  Table  9-2) . 
Any  request  which  requires  the  USR  in  memory  may  also  require  that  a 
portion  of  the  user  program  be  saved  temporarily  on  the  system  device 
scratch  blocks  (i.e.,  be  "swapped  out")  to  provide  room  for  the  USR. 
The  USR  will  be  read  into  the  swapped  region. 

During  most  normal  operations,  this  swapping  is  invisible  to  the  user 
and  he  need  not  be  concerned  about  it.  However,  it  is  possible  to 
optimize  programs  so  that  they  require  little  or  no  swapping.  This  is 
particularly  useful  when  operating  in  an  F/B  environment,  since  under 
the  F/B  system,  the  USR  will  be  swapped  for  both  background  and 
foreground  jobs  regardless  of  which  job  required  it.  If  the  USR  is 
not  swapped,  neither  the  foreground  nor  the  background  job  will  be 
slowed  down  by  the  swapping  process. 

The  following  items  should  be  considered  if  a  swap  operation  is 
necessary: 

1.  The  background  job  -  If  a  .SETTOP  request  in  a  background  job 
specifies  an  address  beyond  the  point  at  which  the  USR 
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normally  resides,  a  swap  will  be  required  when  the  USR  is 
called.  More  details  concerning  the  .SETTOP  request  are  in 
Section  9.4.36. 

2.  The  value  of  location  46  -  If  the  user  either  assembles  an 
address  into  word  46  or  moves  a  value  there  while  the  program 
is  running,  RT-11  uses  the  contents  of  that  word  as  an 
alternate  place  to  swap  the  USR.  If  location  46  is  0,  this 
indicates  that  the  USR  will  be  at  its  normal  location  in  high 
memory. 

NOTES 

1.  If  the  USR  does  not  require 
swapping,  the  value  in  location  46 
is  ignored.  Swapping  is  a 
relatively  time-consuming  operation 
and  is  avoided,  if  possible. 

2.  A  foreground  job  should  always  have 
a  value  in  location  46  unless  it  is 
certain  that  the  USR  will  never  be 
swapped.  If  the  foreground  job  does 
not  allow  space  for  the  USR  and  a 
swap  is  required,  a  fatal  error 
occurs.  (The  SET  USR  NOSWAP 
command,  explained  in  Chapter  2, 
ensures  that  the  USR  will  be 
resident.) 

3.  Care  should  be  taken  when  specifying 
an  alternate  address  to  location  46. 

The  single- job  system  does  not 
verify  the  legality  of  the  USR  swap 
address.  Thus,  if  the  area  to  be 
swapped  overlays  the  Resident 
Monitor,  the  system  is  destroyed. 

4.  The  user  should  also  take  care  that 

the  USR  is  never  swapped  over  any  of 
the  following  areas:  the  program 

stack;  any  parameter  block  for 
calls  to  the  USR;  any  I/O  buffers, 
device  handlers,  or  completion 
routines  being  used  when  the  USR  is 
called. 


The  following  is  an  example  of  the  way  a  background  program  can  use 
all  memory  up  to,  but  not  including,  the  USR.  This  leaves  the  USR 
resident  and  therefore  does  not  require  swapping. 

.MCAll  ,.V2,.,.REGDEF,. SETTOP,. EXIT 
,.V2,, 

.REGOEF 

RMPTR*S4  I  POINTER  TO  RMON  IS  AT  34, 

USRL0C*26t  I  POINTER  TO  USR  LOCATION  IS 

I  AT  2tt  BYTES  INTO  RMON, 

STARTI 

MOV  P4RMPTR, Ri  |R1  RESIDENT  MONITOR 
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MOV  USRL0C(RI),R1 

.SETTOP  Ri 

MOV  R0.HILIM 


I Rt  •»  USR 

I  ASK  FOR  MEMORY  UF  TO  U8R 
|R0  i  HIGH  LIMIT  OF  MEMORY 
I  ACTUALLY  GRANTED  8Y  MONITOR, 


.EXIT 

HILIMt  .WORD  0  I  CONTAINS  HI  LIMIT  OF  MEMORY 

.END  START 


9.2.6  Offset  Words 

There  are  several  words  which  always  have  fixed  positions  relative  to 
the  start  of  the  Resident  Monitor.  It  is  often  advantageous  for  user 
programs  to  be  able  to  access  these  words.  This  is  done  with  the 
code: 

RMON  =  54 

MOV  @# RMON, register 

MOV  OFFSET (register) .register 


Here,  register  is  any  general  register  and  OFFSET  is  a  number  from  the 
following  list: 


OFFSET  (Bytes)  Contents 

262  System  date.  (See  .DATE  request.) 

266  Start  of  normal  USR  area.  This  is  where  the 

USR  will  reside  when  it  is  non-swapping.  It 
is  useful  to  be  able  to  perform  a  .SETTOP  in 
a  background  job  such  that  the  USR  is  always 
resident.  (An  example  is  in  Section  9.2.5.) 

270  Address  of  I/O  exit  routine  for  all  devices. 

The  exit  routine  is  an  internal  queue 
management  routine  through  which  all  device 
handlers  exit  once  the  I/O  transfer  is 
complete.  Any  new  devices  added  to  RT-11 
must  also  use  this  exit  location. 

276  Monitor  version  number  (2-377) .  The  user  can 
always  access  the  version  number  to  determine 
if  the  most  recent  monitor  is  in  use. 

277  Update  number.  Patches  to  the  monitor  always 
increment  the  update  number.  This  provides  a 
means  of  checking  that  all  patches  have  been 
made.  (This  number  should  be  accessed  by 
MOVB  rather  than  MOV) . 

300  Configuration  word.  This  is  a  string  of  16 

bits  used  to  indicate  information  about 
either  the  hardware  configuration  of  the 
system,  or  a  software  condition.  The  bits 
and  their  meanings  are: 
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304-313 


314 


324 


Bit  #  Meaning 

0  0  =  Single-Job  Monitor 

1  =  F/B  Monitor 

2  1  *  GT40  display  hardware  exists 

3  1  =  RT-11  BATCH  is  in  control 

of  the  background  (note  that 
the  BATCH  processor  is  not 
available  at  this  time) 

5  0  =  60-cycle  clock 

1  =  50-cycle  clock 

6  1  -  11/45  floating-point 

hardware  exists 

7  0  =  No  foreground  job  is  in  memory 
1  =*  Foreground  job  is  in  memory 

8  1  »  user  is  linked  to  the  GT40 

scroller 

9  1  =  USR  is  permanently  resident 

(via  a  SET  USR  NOSWAP) 

15  1  =  KW11L  clock  is  present 

The  other  bits  are  reserved  for  future  use 
and  should  not  be  accessed  by  user  programs. 

These  locations  contain  the  addresses  of  the 
console  terminal  control  and  status 
registers.  The  order  is: 

304  Keyboard  status 
306  Keyboard  buffer 
310  Printer  status 
312  Printer  buffer 

These  locations  can  be  changed,  for  example, 
to  reflect  a  second  terminal;  thus  RT-11  can 
be  made  to  run  on  any  terminal  present  on  the 
system  which  is  connected  to  the  machine  via 
the  DL11  multiple  terminal  interface.  (Refer 
to  the  RT-11  SOFTWARE  SUPPORT  MANUAL 
( DEC— 11— ORPGA-B— D ) . 

The  maximum  file  size  allowed  in  a  0  length 
.ENTER.  This  can  be  adjusted  by  the  user 
program  or  by  using  the  PATCH  program  to  be 
any  reasonable  value.  The  default  value  is 
•  177777  (decimal)  blocks,  allowing  an 
essentially  unlimited  file  size. 

Address  of  .SYNCH  entry.  User  interrupt 
routines  may  enter  the  monitor  through  this 
address  to  synchronize  with  the  job  they  are 
servicing. 

Address  of  VT-11  display  processor  display 
stop  interrupt  vector. 
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9.2.7  File  S tructure 

RT-11  uses  a  "contiguous"  file  structure.  This  type  of  structure 
implies  that  every  file  on  the  device  is  made  up  of  a  contiguous  group 
of  physical  blocks.  Thus,  a  file  that  is  9  blocks  long  occupies  9 
contiguous  blocks  on  the  device. 

A  contiguous  area  on  a  device  can  be  in  one  of  the  following 
categories : 

1.  Permanent  file.  This  is  a  file  which  has  been  .CLOSEd  on  a 
device.  Any  named  files  which  appear  in  a  PIP  directory 
listing  are  permanent  files. 

2.  Tentative  file.  Any  file  which  has  been  created  via  .ENTER, 
but  not  .CLOSEd,  is  a  tentative  file  entry.  When  the  .CLOSE 
request  is  given,  the  tentative  entry  becomes  a  permanent 
file.  If  a  permanent  file  already  exists  under  the  same 
name,  the  old  file  is  deleted.  If  a  .CLOSE  is  never  given, 
the  tentative  file  is  treated  like  an  empty  entry. 

3.  Empty  entry.  When  disk  space  is  unused  or  a  permanent  file 
is  deleted,  an  empty  entry  is  created.  Empty  entries  appear 
in  a  PIP  /E  directory  listing  as  <UNUSED>  N,  where  N  is  the 
decimal  length  of  the  empty  area* 

Since  a  contiguous  structure  does  not  automatically  reclaim  unused 
disk  space,  the  device  may  eventually  become  "fragmented".  A  device  is 
fragmented  when  there  are  many  empty  entries  which  are  scattered  over 
the  device.  RT-11  PIP  has  an  option  which  allows  the  user  to  collect 
all  empty  areas  so  that  they  occur  at  the  end  of  a  device.  Refer  to 
Chapter  4  for  details. 


9.2.8  Completion  Routines 

Completion  routines  are  user-written  routines  which  are  entered 
following  an  operation.  On  entry  to  a  completion  routine,  RO  contains 
the  channel  status  word  for  the  operation;  R1  contains  the  octal 
channel  number  of  the  operation.  The  carry  bit  is  not  significant. 

Completion  routines  are  handled  differently  in  the  Single- Job  and  the 
F/B  versions  of  RT-11.  In  the  Single-Job  version,  completion  routines 
are  totally  asynchronous  and  can  interrupt  one  another.  In  F/B, 
completion  routines  do  not  interrupt  each  other.  Instead  they  are 
queued  and  made  to  wait  until  the  correct  job  is  running.  For 
example,  if  a  foreground  job  is  running  and  an  I/O  transfer  initiated 
by  a  background  job  completes  and  wants  to  go  to  a  completion  routine, 
the  background  routine  is  queued  and  will  not  execute  until  the 
foreground  gives  up  control  of  the  system.  If  the  foreground  is 
running  and  a  foreground  I/O  transfer  completes  and  wants  a  completion 
routine,  that  routine  will  be  entered  immediately  if  the  foreground  is 
not  already  inside  a  completion  routine.  If  it  is  in  a  completion 
routine,  that  routine  continues  to  termination,  at  which  point  any 
other  completion  routines  are  entered  in  a  first  in/first  out  manner. 
If  the  background  is  running  and  a  foreground  I/O  transfer  completes 
and  needs  a  completion  routine,  the  background  is  suspended  and  the 
foreground  routine  is  entered  immediately. 
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The  restrictions  which  must  be  observed  when  writing  completion 
routines  ares 

1.  Completion  functions  cannot  issue  a  request  which  would  cause 
the  USR  to  be  swapped  in.  They  are  primarily  used  for 
issuing  READ/WRITE  commands,  not  for  opening  or  closing 
files,  etc.  A  fatal  monitor  error  is  generated  if  the  USR  is 
called  from  a  completion  routine. 

2.  Completion  routines  should  never  reside  in  the  memory  space 
which  will  be  used  for  the  USR,  since  the  USR  can  be 
interrupted  when  I/O  terminates  and  the  completion  routine  is 
entered.  If  the  USR  has  overlaid  the  routine,  control 
passes  to  a  random  place  in  the  USR,  with  a  HALT  or  error 
trap  the  likely  result. 

3.  The  routine  must  be  exited  via  an  RTS  PC,  as  it  is  called 
from  the  monitor  via  a  JSR  PC,ADDR  where  ADDR  is  the 
user-supplied  address. 

4.  If  a  completion  routine  uses  registers  other  than  RO  or  Rl, 
it  must  save  them  upon  entry  and  restore  them  before  exiting. 


9.2.9  Using  the  System  Macro  Library 

User  programs  for  RT-11  should  always  be  written  using  the  system 
macro  library  (SYSMAC.SML) ,  supplied  with  RT-11.  This  ensures 
compatibility  among  all  user  programs  and  allows  easy  modification  by 
redefining  a  macro.  A  listing  of  SYSMAC.SML  appears  in  Appendix  D. 

The  system  macro  library  for  8K  systems  appears  on  the  system  device 
as  SYSMAC.8K. 

Suggestions  for  writing  foreground  programs  are  in  Appendix  H,  F/B 
Programming  and  Device  Handlers.  This  appendix  should  be  read  in 
conjunction  with  Chapter  9  before  coding  F/B  programs. 


9.3  TYPES  OF  PROGRAMMED  REQUESTS 

There  are  three  types  of  services  which  the  monitor  makes  available  to 
the  user  through  programmed  requests.  These  ares 

1.  Requests  for  File  Manipulation 

2.  Requests  for  Data  Transfer 

3.  Requests  for  Miscellaneous  Services 

Table  9-1  summarizes  the  programmed  requests  in  each  of  these 
categories  alphabetically.  Those  marked  with  an  asterisk  function 
only  in  a  F/B  environment;  they  are  ignored  under  the  Single- Job 
Monitor.  The  EMT  and  function  code  for  each  request  (where 
applicable)  are  included. 
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Table  9-1 

Summary  of  Programmed  Requests 


Mnemonic 

EMT  & 
Code 

Section 

Purpose 

File  Manipulation  Requests 

*.CHCOPY 

375 

13 

9.4.3 

Establishes  a  link  and  allows  one 
job  to  access  another  job's 
channel . 

.CLOSE 

375 

7 

9.4.4 

Closes  the  specified  channel. 

. DELETE 

375 

0 

9.4.10 

Deletes  the  file  from  the  specified 
device. 

.ENTER 

375 

2 

9.4.13 

Creates  a  new  file  for  output. 

.LOOKUP 

375 

1 

9.4.21 

Opens  an  existing  file  for  input 
and/or  output  via  the  specified 
channel. 

.RENAME 

375 

4 

9.4.32 

Changes  the  name  of  the  indicated 
file  to  a  new  name. 

.REOPEN 

375 

6 

9.3.33 

Restores  the  parameters  stored  via 
a  SAVESTATUS  request  and  reopens 
the  channel  for  I/O. 

.SAVESTATUS 

375 

5 

9.4.34 

Saves  the  status  parameters  of  an 
open  file  in  user  memory  and  frees 
the  channel  for  future  use. 

Data  Transfer  Requests 

*.RCVD 
*.RCVDW 
* . RCVDC 

375 

26 

9.4.29 

Receives  data.  Allows  a  job  to 
read  messages  or  data  sent  by 
another  job  in  an  F/B  environment. 
The  three  modes  correspond  to  the 
READ,  .READC,  and  READW  modes. 

.READ 

375 

10 

9.4.30 

Transfers  data  via  the  specified 
channel  to  a  memory  buffer  and 
returns  control  to  the  user  program 
when  the  transfer  request  is 
entered  in  the  I/O  queue.  No 
special  action  is  taken  upon 
completion  of  I/O. 

•RE ADC 

375 

10 

9.4.30 

Transfers  data  via  the  specified 
channel  to  a  memory  buffer  and 
returns  control  to  the  user  program 
when  the  transfer  request  is 

entered  in  the  I/O  queue.  Upon 

completion  of  the  read,  control 
transfers  asynchronously  to  the 

routine  specified  in  the  .READC 
request. 
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Summary  of  Programmed  Requests 


Mnemonic 

EMT 

& 

Section 

Purpose 

Code 

•  READW 

375 

10 

9.4.30 

Transfers  data  via  the  specified 
channel  to  a  memory  buffer  and 
returns  control  to  the  user  program 
only  after  the  transfer  is 
complete. 

*.SDAT 

375 

25 

9.4.35 

Allows  the  user  to  send  messages  or 

* . SDATC 

data  to  the  other  job  in  an  F/B 

* . SDATW 

environment.  The  three  modes  cor¬ 
respond  to  the  .WRITE ,  .WRITC  and 
.WRITW  modes. 

.TTYIN 

340 

9.4.43 

Transfers  one  character  from  the 

.TTINR 

keyboard  buffer  to  R0. 

.TTYOUT 

341 

... 

9.4.44 

Transfers  one  character  from  R0 

• TTOUTR 

to  the  terminal  input  buffer. 

.WRITE 

375 

11 

9.4.47 

Transfers  data  via  the  specified 
channel  to  a  device  and  returns 

control  to  the  user  program  when 
the  transfer  request  is  entered  in 
the  I/O  queue.  No  special  action 
is  taken  upon  completion  of  the 
I/O. 

.WRITC 

375 

11 

9.4.47 

Transfers  data  via  the  specified 
channel  to  a  device  and  returns 
control  to  the  user  program  when 
the  transfer  request  is  entered  in 
the  I/O  queue.  Upon  completion  of 
the  write ,  control  transfers 
asynchronously  to  the  routine 
specified  in  the  .WRITC  request. 

.WRITW 

375 

11 

9.4.47 

Transfers  data  via  the  specified 
channel  to  a  device  and  returns 
control  to  the  user  program  only 
after  the  transfer  is  complete. 

Miscellaneous  Services 

•  CDFN 

375 

15 

9.4.1 

Defines  additional  channels  for 

doing  I/O. 

.CHAIN 

374 

10 

9.4.2 

Chains  to  another  program  (in  the 
background  job  only) . 

* .CMKT 

375 

23 

9.4.5 

Cancels  an  unexpired  mark  time 

request. 

* . CNTXSW 

375 

33 

9.4.6 

Requests  that  the  indicated  memory 
locations  be  part  of  the  F/B 
context  switch  process. 

.CSIGEN 

344 

— 

9.4.7 

Calls  the  Command  String 

Interpreter  (CSI)  in  general  mode. 

.CSISPC 

345 

— 

9.4.8 

Calls  the  CSI  in  special  mode. 
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Summary  of  Programmed  Requests 


Mnemonic 

EMT  & 
Code 

Section 

Purpose 

*.CSTAT 

375 

27 

9.4.9 

Returns  the  status  of  the  channel 
indicated. 

.DATE 

— 

— 

9. 3.1.1 

Moves  the  current  date  information 
into  R0. 

*. DEVICE 

375 

14 

9.4.11 

Allows  user  to  turn  off  device 
interrupt  enable  in  F/B  upon 
program  termination. 

• DSTATUS 

342 

— 

9.4.12 

Returns  the  status  of  a  particular 
device. 

.EXIT 

350 

— 

9.4.14 

Exits  the  user  program  and  returns 
control  to  the  Keyboard  Monitor, 

.FETCH 

343 

— 

9.4.15 

Loads  device  handlers  into  memory. 

.GTIM 

375 

21 

9.4.16 

Gets  time  of  day. 

.GTJB 

375 

20 

9.4.17 

Gets  parameters  of  this  job. 

.HERR 

374 

5 

9.4.18 

Specifies  termination  of  the  job  on 
fatal  errors. 

.HRESET 

357 

— 

9.4.19 

Terminates  I/O  transfers  and  does  a 
•SRESET  operation. 

.INTEN 

9. 3. 1.2 

Notifies  monitor  that  an  interrupt 
has  occurred  and  to  switch  to 
"system  state" f  and  sets  the 
processor  priority  to  the  correct 
value • 

.LOCK 

346 

9.4.20 

Makes  the  monitor  User  Service 
Routines  (USR)  permanently  resident 
until  .EXIT  or  .UNLOCK  is  executed. 
The  user  program  is  swapped  out  if 
necessary. 

*.MRKT 

375 

22 

9.4.22 

Marks  time;  i.e.,  sets 
asynchronous  routine  to  occur  after 
a  specified  interval. 

* .MWAIT 

374 

11 

9.3.23 

Waits  for  messages  to  be  processed. 

.PRINT 

351 

— 

9.4.24 

Outputs  an  ASCII  string  to  the 
terminal. 

* . PROTECT 

375 

31 

9.4.25 

Requests  that  vectors  in  the  area 
from  0-476  be  given  exclusively  to 
this  job. 

.PURGE 

374 

3 

9.4.26 

Clears  out  a  channel. 

.QSET 

353 

— 

9.4.27 

Expands  the  size  of  the  monitor  I/O 
queue . 

. RCTRLO 

355 

— 

9.4.28 

Enables  output  to  the  terminal. 

(continued  on  next  page) 
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Summary  of  Programmed  Requests 


Mnemonic 

EMT  & 
Code 

Section 

Purpose 

• REGDEF 

—  —  — 

“  — 

9. 3. 1.3 

Defines  the  PDP-11  general 

registers. 

.RELEAS 

343 

— 

9.4.31 

Removes  device  handlers  from 

memory. 

*.RSUM 

374 

2 

9.4.39 

Causes  the  main  line  of  the  job  to 
be  resumed  where  it  was  suspended 
with  .SPND. 

.SERR 

374 

4 

9.4.18 

Inhibits  most  fatal  errors  from 
causing  the  job  to  the  aborted* 

.SETTOP 

354 

—  — 

9.4.36 

Specifies  the  highest  memory 
location  to  be  used  by  the  user 
program. 

.SFPA 

375 

30 

9.4.37 

Sets  user  interrupt  for  floating 
point  processor  exceptions. 

.SPFUN 

375 

32 

9.4.38 

Performs  special  functions  on 

magtape  and  cassette  units. 

* .SPND 

374 

1 

9.4.39 

Causes  the  running  job  to  be 

suspended. 

.SRESET 

352 

— 

9.4.40 

Resets  all  channels  and  releases 
the  device  handlers  from  memory. 

.SYNCH 

9. 3. 1.4 

Enables  user  program  to  perform 
monitor  programmed  requests  from 
within  an  interrupt  service 
routine. 

* . TLOCK 

374 

7 

9.4.41 

Indicates  if  the  USR  is  currently 
being  used  by  another  job  and 
performs  a  .LOCK  if  available. 

.TRPSET 

375 

3 

9.4.42 

Sets  a  user  intercept  for  traps  to 
locations  4  and  10. 

* .TWAIT 

375 

24 

9.4.45 

Suspends  the  running  job  for  a 
specified  amount  of  time. 

.UNLOCK 

347 

—  — 

9.4.20 

Releases  USR  if  a  LOCK  was  done. 
The  user  program  is  swapped  in  if 
required. 

•  •  V2  •  . 

- — 

— 

9. 3. 1.5 

Enables  expansions  to  occur  in 

Version  2  format. 

.WAIT 

374 

0 

9.4.46 

Waits  for  completion  of  all  I/O  on 
a  specified  channel. 

Requests  requiring  the  USR  (as  explained  in  Section  9 .2. 5)  differ 
between  the  Single- Job  and  F/B  Monitors.  Table  9-2  indicates  which 
requests  require  the  USR  to  be  in  memory.  Those  requests  marked  by  an 
asterisk  are  Version  2  macros  only.  The  CLOSE  request  on  non-file 
structured  devices  (LP,  PP,  TT,  etc.)  does  not  require  the  USR  under 
either  monitor. 
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Table  9-2 

Requests  Requiring  the  USR 


Request 

F/B 

Single- Job 

* • CDFN 

No 

Yes 

♦.CHAIN 

NO 

No 

* . CHCOPY 

No 

N/A 

.CLOSE  (see  Note  1) 

Yes 

Yes 

*.CMKT 

No 

N/A 

* . CNTXSW 

No 

N/A 

.CSIGEN 

Yes 

Yes 

.CSISPC 

Yes 

Yes 

* . CSTAT 

No 

N/A 

.DELETE 

Yes 

Yes 

♦.DEVICE 

No 

N/A 

.DSTATUS 

Yes 

Yes 

.ENTER 

Yes 

Yes 

.EXIT 

No 

No 

.FETCH 

Yes 

Yes 

* . GTIM 

No 

No 

* . GT JB 

No 

No 

*.IIERR 

No 

No 

.HRESET 

No 

Yes 

.LOCK  (see  Note  2) 

Yes 

Yes 

.LOOKUP 

Yes 

Yes 

* .MRKT 

No 

N/A 

♦.MWAIT 

No 

N/A 

.PRINT 

No 

NO 

* . PROTECT 

No 

N/A 

♦.PURGE 

No 

No 

.QSET 

Yes 

Yes 

. RCTRLO 

No 

No 

* . RCVD/RCVDC/RCVDW 

No 

N/A 

.  READ/READC/.READW 

No 

No 

.RE LEAS 

Yes 

Yes 

.RENAME 

Yes 

Yes 

.REOPEN 

No 

No 

♦.RSUM 

No 

N/A 

. SAVES TATUS 

No 

No 

* . SDAT/SDATC/SDATW 

No 

N/A 

*.SERR 

No 

No 

.SETTOP 

No 

No 

♦ .SFPA 

No 

No 

♦.SPFUN 

No 

No 

*.SPND 

No 

N/A 

♦.SRESET 

No 

Yes 

* . TLOCK  (see  Note  3) 

No 

No 

* .TRPSET 

No 

No 

.TTINR/.TTYIN 

No 

No 

. TTOUTR/ . TTY OUT 

No 

No 

♦.TWAIT 

No 

N/A 

.UNLOCK 

No 

No 

.WAIT 

No 

No 

. WRITE /WRITC/WRITW 

No 

No 
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Note  1:  Only  if  channel  was  opened  via  .ENTER. 

Note  2:  Only  if  USR  is  in  a  swapping  state. 

Note  3:  Only  if  USR  is  not  in  use  by  the  other  job. 


9.3.1  System  Macros 

The  following  five  macros  are  included  in  the  system  macro  library, 
but  are  not  programmed  requests  in  that  they  cause  no  EMT  instruction 
to  be  generated: 

.DATE  .SYNCH 

.INTEN  . . V2 . . 

• REGDEF 

They  can  be  used  in  the  same  manner  as  the  other  macro  calls;  their 
explanations  follow. 


.DATE 


9. 3. 1.1  .DATE 

This  request  moves  the  current  date  information  from  the  system  date 
word  into  RO.  The  date  word  returned  is  in  the  following  format: 


Bit:  14  10  9  54  0 


MONTH 

DAY 

YEAR-72 (DECIMAL) 

(1-12.) 

(1-31.) 

Macro  Call:  .DATE 

Errors : 

No  errors  are  returned.  A  zero  result  in  RO  indicates  that  no  DATE 
command  was  entered. 
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.INTEN 


9. 3.1.2  .INTEN 

This  request  is  used  by  user  program  interrupt  service  routines  to: 

1.  Notify  the  monitor  that  an  interrupt  has  occurred  and  to 
switch  to  "system  state", 

2.  Set  the  processor  priority  to  the  correct  value. 

In  Version  2  of  RT-11,  all  external  interrupts  cause  the  processor  to 
go  to  level  7  (see  Appendix  H) .  .INTEN  is  used  to  lower  the  priority 
to  the  value  at  which  the  device  should  be  run.  On  return  from 
.INTEN,  the  device  interrupt  can  be  serviced,  at  which  point  the 
interrupt  routine  returns  via  an  RTS  PC.  It  is  very  important  to  note 
that  an  RTI  will  not  return  correctly  from  an  interrupt  routine  which 
specifies  an  .INTEN. 

Macro  Call:  .INTEN  .priority,  pic 

where:  .priority  is  the  processor  priority  at  which  the  user 

wishes  to  run  his  interrupt  routine. 

pic  is  an  optional  argument  which  should  be 

non-blank  if  the  interrupt  routine  is  written 
as  a  PIC  (position  independent  code)  routine. 
If  the  routine  does  not  have  to  be  PIC,  it  is 
recommended  that  the  PIC  field  be  left  blank; 
the  non-PIC  version  is  slightly  faster  than 
the  PIC  version. 

The  user  is  advised  to  read  Appendix  H  for  more  details  concerning  the 
use  of  .INTEN  and  .SYNCH. 

Errors : 

None. 

Example: 

Refer  to  Section  9. 3. 1.4,  .SYNCH,  for  an  example. 
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.REGDEF 


9. 3. 1.3  .REGDEF 

This  macro  call  defines  the  PDP-11  general  registers  as  RO  through  R5, 
SP ,  and  PC . 

Macro  Call:  .MCALL  .REGDEF,... 

.REGDEF 

Errors : 

None. 

Example : 

Refer  to  the  example  for  the  .SYNCH  request.  Appendix  D  shows  the 
expansion  of  .REGDEF. 


.SYNCH 


9. 3.1.4  .SYNCH 

This  macro  call  enables  the  user  program  to  perform  monitor  programmed 
requests  from  within  an  interrupt  service  routine.  Unless  a  .SYNCH  is 
used,  issuing  programmed  requests  from  interrupt  routines  is  not 
supported  by  the  system  and  should  not  be  performed.  .SYNCH,  like 
.INTEN  and  .DATE,  is  not  a  programmed  request  and  generates  no 

EMT  instructions. 

Macro  Call:  .SYNCH  .area 

where:  .area  is  the  address  of  a  seven-word  area  which  the 

user  must  set  aside  for  use  by  .SYNCH.  The 
7-word  block  appears  as: 

Word  1  RT-11  maintains  this  word;  its 

contents  should  not  be  altered  by 
the  user. 

Word  2  The  current  job's  number.  This  can 
be  obtained  by  a  .GTJB  call. 

Word  3  Unused. 


9-22 


Programmed  Requests 


Word 

4 

Unused, 

Word 

5 

RO  argument • 

When  a 

successful 

return  is  made  from 

.SYNCH,  RO 

contains  this 

argument • 

Word 

6 

Must  be  -1, 

Word 

7 

Must  be  0. 

Note: 

.SYNCH  assumes  that  the  user  has  not  pushed  anything  on  the  stack 
between  the  .INTEN  and  .SYNCH  calls.  This  rule  must  be  observed  for 
proper  operation.  * 

Errors : 

The  monitor  returns  to  the  location  immediately  following  the  .SYNCH 
if  the  .SYNCH  was  rejected.  The  routine  is  still  unable  to  issue 
programmed  requests,  and  R4  and  R5  are  available  for  use.  Errors 
returned  are  due  to  one  of  the  following: 

1.  Another  .SYNCH  which  specified  the  same  7-word  block  is  still 
pending. 

2.  An  illegal  job  number  was  specified  in  the  second  word  of  the 
block.  The  only  currently  legal  job  numbers  are  0  and  2. 

3.  If  the  job  has  been  aborted  or  for  some  reason  is  no  longer 
running,  the  .SYNCH  will  fail. 

Normal  return  is  to  the  word  after  the  error  return  with  the  routine 
in  user  state  and  thus  allowed  to  issue  programmed  requests.  RO 
contains  the  argument  which  was  in  word  4  of  the  block.  RO  and  R1  are 
free  to  be  used  without  having  to  be  saved.  (R4  and  R5  are  not  free.) 
Exit  from  the  routine  should  be  done  via  an  RTS  PC. 

Example : 

.MCALL  ,.V2..,.REGDEF 
a  a  V2. a 
,  REGDEF 


.MCALL 

.GTJB, .INTEN, 

•NRITC,. SYNCH, .EXIT, .PRINT 

8TARTI 

MOV 

# JOB , R5 

I0UTPUT  OF  .GTJB  GOES  HERE 

,GTJS 

#AREA,R5 

I  GET  JOB  NUMBER 

MOV 

(R5),SYNBLK*2 

) STORE  THE  JOB  NUMBER  INTO  SYNCH  BLOCK 
FIN  HERE  WE  SET  UP  INTERRUPT 
IPRQCESSING,  AND  START  UP  THE 
t INTERRUPTING  DEVICE. 

INTRPTI 

a INTEN 

5 

f  GO  INTO  SYSTEM  STATE 

I  RUN  AT  LEVEL  FIVE 

1  INTERRUPT  PROCESSING  -- 
>  NOTHING  CAN  GO  ON  STACK 

.SYNCH 

RSYNBLK 

» TIME  TO  WRITE  A  BUFFER 

BR 

SYNFAIL 

1  SYNCH  FAILED 

I  SYNCH  SUCCEEDED 

.WRITC 

RARE A, CHAN, BUFF, WCNT,#CRTN1,§LK 

IWRITE  A  BUFFER 
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SCS  WTFAll  I  FAILED  SOMEHOW 


RTS  PC 
SYNBLK I  .WORD  0 
•WORD  0 
.WORD  0 
.WORD  S 

.WORD  0fl'0 

SYNFAILl 


IRE-INXTXALXZE  FOR  MORE 
I  INTERRUPTS  AND  EXIT 

I  JOB  NUMBER 

I R0  CONTAINS  5  ON  SUCCESSFUL 
I, SYNCH 

I  SET  UP  FOR  MONITOR 


9. 3. 1.5  . . V2. . 


This  macro  enables  macro  expansions  to  occur  In  Version  2  format.  If 
..V2..  is  not  used,  all  macro  expansions  will  be  in  Version  1  format. 
Note  that  any  requests  marked  with  an  asterisk  in  Table  9-1  are  not 
valid  as  Version  1  requests,  and  thus  will  be  flagged  as  errors  when 
they  are  assembled  in  Version  1  form.  If  ..V2..  is  used,  all  macros 
are  generated  in  Version  2  form.  Note  also  that  using  ..V2..  causes  a 
symbol  ...V2  to  be  defined.  User  programs  should  not  use  this  symbol. 

Macro  Call:  .MCALL  . .V2.. 

. .V2. . 

. ,V2. .  should  first  be  loaded  with  an  .MCALL  command  and  then  invoked. 
Note: 

It  is  possible  that  user  programs  will  exist  in  which  both  Version  1 
and  Version  2  macros  are  present.  To  allow  proper  assembly,  the  user 
should  not  call  ..V2..  as  described;  instead  he  should  include  the 
statement : 


.MCALL  . . . CM1 , • • . CM2 , . . . CM3 , • • • CM 4 

to  define  the  utility  macros  (CM1,  CM2,  etc.)  used  by  other  Version  2 
macros.  This  causes  all  macros  which  existed  in  Version  1  to  assemble 
in  Version  1  format,  while  all  macros  which  are  new  to  Version  2  are 
correctly  generated  as  Version  2  macros. 

Example : 

Refer  to  the  example  for  the  .CDFN  directive. 
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9.4  PROGRAMMED  REQUEST  USAGE 


This  section  provides  a  description  of  each  of  the  programmed  requests 
alphabetically.  The  following  parameters  are  commonly  used  as 
arguments  in  the  various  calls: 

.addr 

an  address,  the  meaning  of  which  depends  on  the 
request  being  used 

.area 

a  pointer  to  the  EMT  argument  list  (for  those 
requests  which  require  a  list);  see  Section  9.2.3 

.blk 

a  block  number  specifying  the  relative  block  in  a 
file  where  an  I/O  transfer  is  to  begin 

.buff 

a  buffer  address  specifying  a  memory  location  into 
or  from  which  an  I/O  transfer  is  to  be  performed 

.chan 

a  channel  number  in  the  range  0-377 (octal) 

.crtn 

the  entry  point  of  a  completion  routine;  see 

Section  9.2.8 

.count 

file  number  for  magtape/cassette  operations  (see 
Appendix  H) ;  if  this  argument  is  blank,  a  value  of 
0  is  assumed 

.dblk 

the  address  of  a  four-word  RAD50  descriptor  of  the 
file  to  be  operated  upon;  see  Section  9.2.2 

•  num 

a  number,  the  value  of  which  depends  on  the 
request 

.went 

a  word  count  specifying  the  number  of  words  to  be 
transferred  to  or  from  the  buffer  during  an  I/O 
operation 

Additional  information  concerning  these  parameters  (and  others  not 
defined  here)  is  provided  as  necessary  under  each  request. 


CDFN 


9.4.1  .CDFN 

The  .CDFN  request  is  used  to  redefine  the  number  of  I/O  channels. 
Each  job,  whether  foreground  or  background,  is  initially  provided  with 
16 (decimal)  I/O  channels .  .CDFN  allows  the  number  to  be  expanded  to 
as  many  as  256  (decimal)  channels. 

Note  that  .CDFN  defines  new  channels;  the  previously-defined  channels 
are  not  used.  Thus,  a  .CDFN  for  20 (decimal)  channels  (while  the  16 
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original  channels  are  defined)  causes  only  20  I/O  channels;  the  space 
for  the  original  16  is  unused. 

Macro  Call:  .CDFN  .area,  .addr,  .num 

where:  .addr  is  the  address  where  the  I/O  channels  begin 

.num  is  the  number  of  I/O  channels  to  be  created 

Request  Format: 

R0  4 .area: 


15  0 


.addr 


.num 


The  space  used  to  contain  the  new  channels  is  taken  from  within  the 
user  program.  Each  I/O  channel  requires  5  words  of  memory.  Thus,  the 
user  must  allocate  5*N  words  of  memory,  where  N  is  the  number  of 
channels  to  be  defined. 

It  is  recommended  that  the  .CDFN  request  be  used  at  the  beginning  of  a 
program,  before  any  I/O  operations  have  been  initiated.  If  more  them 
one  .CDFN  request  is  used,  the  channel  areas  must  either  start  at  the 
same  location  or  not  overlap  at  all.  The  two  requests  .SRESET  and 
.HRESET  cause  the  user's  channels  to  revert  to  the  original  16 
channels  defined  at  program  initiation.  Hence,  any  .CDFNs  must  be 
reissued  after  using  those  directives. 

Errors : 

Code  Explanation 

0  An  attempt  was  made  to  define  fewer  channels  than 

already  exist. 


Example : 


.MCALL 

..VE.. 

..V2..». REGDEF 

.REGDEF 

.MCALl 

.CDFN, .PRINT, . 

EXIT 

START  1 

.CDFN 

#R0LIST,#CMANU 

BCS 

BAOCDF 

.PRINT 

.EXIT 

•  MSG  1 

BADCOFl 

.PRINT 

.EXIT 

•  MSG2 

MSG  1 1 

. A  SC  I Z 

/.CDFN  0.K ,  / 

.EVEN 

M3G2I 

.  ASCIZ 
.EVEN 

/BAD  ,CDFN/ 

R0LI3TI 

.BURN 

3 

ISMT 

ARGUMENT  LIST 

CMANII 

•  BIKW 

40. *5 

IR00M 

FOR  CHANNELS 

.ENO 

START 

The  example  defines  40  (decimal)  channels  to  start  at  location  CHANL. 
An  error  occurs  if  40  or  more  channels  are  already  defined. 
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.CHAIN 


9.4.2  .CHAIN 

This  request  allows  a  background  program  to  pass  control  directly  to 
another  background  program  without  operator  intervention.  Since  this 
process  may  be  repeated,  a  large  "chain"  of  programs  can  be  strung 
together. 

The  area  from  locations  500-507  contains  the  device  name  and  file  name 
(in  RAD50)  to  be  chained  to,  and  the  area  from  locations  510-777  is 
used  to  pass  information  between  the  chained  programs. 

Macro  Call:  .CHAIN 

Notes : 

1.  No  assumptions  should  be  made  concerning  which  areas  of 
memory  will  remain  intact  across  a  .CHAIN.  In  general, 
500-777  is  the  only  area  guaranteed  to  be  preserved  across 
a  .CHAIN. 

2.  I/O  channels  are  left  open  across  a  .CHAIN  for  use  by  the  new 
program.  However,  I/O  channels  opened  via  a  .CDFN  request 
are  not  available  in  this  way.  Since  the  monitor  reverts  to 
to  the  original  16  channels  during  a  .CHAIN,  programs  which 
leave  files  open  across  a  .CHAIN  should  not  use  .CDFN. 
Furthermore,  non-resident  device  handlers  are  released  during 
a  .CHAIN,  and  must  be  .FETCHed  again  by  the  new  program. 

3.  If  a  program  normally  loads  into  the  area  500-777,  bit  8  of 
the  JSW  should  be  set  during  program  assembly.  This  causes 
the  monitor  to  load  the  area  properly.  If  the  bit  is  not 
set,  locations  500-777  are  preserved  from  the  chaining 
program,  causing  the  new  program  to  malfunction. 

Errors : 

.CHAIN  is  implemented  by  simulating  the  monitor  RUN  command  (described 
in  Chapter  2) ,  and  can  produce  any  errors  which  RUN  can  -produce.  If 
an  error  occurs,  the  .CHAIN  is  abandoned  and  the  Keyboard  Monitor  is 
entered. 

When  using  .CHAIN,  care  should  be  taken  for  initial  stack  placement, 
since  the  program  being  "chained  to"  is  started.  The  Linker  normally 
defaults  the  initial  stack  to  1000 (octal);  if  caution  is  not  observed, 
the  stack  may  destroy  chain  data  before  it  can  be  used. 
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Example : 


START  t 


LOOP  I 


CHPTRj 


,MCALL  ,,V2,.,,0E6OEF 

, , V2, , 

.REGDEF 

«HCALL  .CHAIN,, TTYIN 


MOV 

#500, RJ 

1  SET  UP  TO  CHAIN 

MOV 

*CHPTR,R2 

I0EVICE,  FILE  NAME  TO  500-511 

,REPT 

4 

MOV 

.ENOR 

(02) ♦, (Rl)* 

.TTYIN 

INOM  GET  A  COMMAND  LINE 

MOVB 

00,  CRD* 

fAND  PASS  IT  TO  THE  JOB 

CHPB 

00, #12 

1  IN  LOCATIONS  512  AND  UP 

BNE 

LOOP 

1  LOOP  UNTIL  LINE  FEEO 

CLR8 

.CHAIN 

(Rl)* 

1  PUT  IN  A  NULL  BYTE 

.RAD50 

/OK  / 

.RAO50 

/TECO  / 

. RAO50 

/SAV/ 

.END 

START 

.CHCOPY 


9.4.3  .CHCOPY  (F/B  only) 

The  .CHCOPY  request  opens  a  channel  for  input,  logically  connecting  it 
to  a  file  which  is  currently  open  by  the  other  job  for  either  input  or 
output.  This  request  may  be  used  by  either  the  foreground  or  the 
background.  .CHCOPY  must  be  done  before  each  .READ  and  .WRITE. 

Macro  Call:  .CHCOPY  .area,  .chan,  .ochan 

where:  .chan  is  the  channel  which  the  job  will  use  to  read 

the  data. 

.ochan  is  the  channel  number  of  the  other  job  which 

is  to  be  copied 


Request  Format: 

RO  .area: 


13  .chan 


.ochan 


.CHCOPY  is  legal  only  on  files  which  sure  on  disk  or  DECtape;  however, 
no  errors  are  detected  by  the  system  if  another  device  is  used. 

Notes : 


1.  If  the  other  job’s  channel  was  opened  via  an  .ENTER  in  order 
to  create  a  file,  the  copier's  channel  indicates  a  file  which 
extends  to  the  highest  block  that  the  creator  of  the  file  had 
written  at  the  time  the  .CHCOPY  was  executed. 
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2.  A  channel  which  is  open  on  a  non-file  structured  device 
should  not  be  copied ,  because  intermixture  of  buffer  requests 
may  result. 

3.  A  program  can  write  to  a  file  (which  is  being  created  by  the 
other  job)  on  a  copied  channel  just  as  it  could  if  it  were 
the  creator.  When  the  copier's  channel  is  closed,  however, 
no  directory  update  takes  place. 

Errors : 

Code  Explanation 

0  Other  job  does  not  exist,  does  not  have 

enough  channels  defined,  or  does  not  have  the 
specified  channel  ( . ochan)  open. 

1  Channel  ( .chan)  already  open. 

Example : 

In  this  example,  .CHCOPY  is  used  to  read  data  currently  being  written 
by  the  other  job.  The  correct  block  number  and  channel  to  read  is 
obtained  by  a  .RCVDW  command.  The  channel  number  will  be  in  MSG+4. 


,NCAU 
. . V2 . . 

, • V2 . . . . REGOEP 

.REGOEF 

.MCAU 

, CHCOPY, .RCVDW, 

.PURGE, .READW, .EXIT, .PRINT 

STI 

.PURGE 

K 

1  MAKE  SURE  WE  HAVE  CLEAR 
(CHANNEL 

.RCVDW 

PARE  A , PHSG, *2 

(READ  TWO  WORDS,  BLOCK  P 
(AND  CHANNEL 

BCS 

NOJOB 

(NO  JOB  THERE 

.CHCOPY 

PARE A , P0»  H8G*A 

(CHANNEL  P  IS  IN  THERE 

BCS 

BUSY 

(but  Busy 

.REAOW 

PARE  A , P0, PBUPP . 

»25fc,,MSG*2  (GET  ThE  CORRECT  BLOCK 

BCS 

ROERR 

.PRINT 

.EXIT 

POKMSG 

NOJOB  t 

.PRINT 

.EXIT 

PMSG1 

BUSY  1 

.PRINT 

.EXIT 

PHSG2 

ROERRl 

.PRINT 

.EXIT 

PMSC3 

AREAS 

.BLKW 

5 

■ 

NS6I 

.BLKW 

5 

sum 

.BUKW 

25P , 

MS61I 

.ASCII 

/NO  JOB  1 / 

HSG2I 

.ASCII 

/BUSY  1 / 

M3G3I 

.ASCII 

/READ  ERROR/ 

OKMSGt 

.ASCII 

/READ  OX/ 

.EVEN 

.EXIT 

.END 

ST 
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.CLOSE 


9.4.4  .CLOSE 

The  .CLOSE  request  terminates  activity  on  the  specified  channel  and 
frees  it  for  use  in  another  operation.  The  handler  for  the  associated 
device  must  be  in  memory. 

Macro  Call:  .CLOSE  .chan 


Request  Format: 


RO  * 


7 


.chan 


A  .CLOSE  is  required  on  any  channel  opened  for  either  input  or  output. 
A  .CLOSE  request  specifying  a  channel  that  is  not  opened  is  ignored. 


A  .CLOSE  performed  on  a  file  which  was  opened  via  .ENTER  causes  the 
device  directory  to  be  updated  to  make  that  file  permanent.  A  file 
opened  via  .LOOKUP  does  not  require  any  directory  operations.  If  the 
device  associated  with  the  specified  channel  already  contains  a  file 
with  the  same  name  and  extension ,  the  old  copy  is  deleted  when  the  new 
file  is  made  permanent.  When  an  entered  file  is  .CLOSEd,  its 
permanent  length  reflects  the  highest  block  written  since  it  was 
entered;  for  example,  if  the  highest  block  written  is  block  number  0, 
the  file  is  given  a  length  of  1;  if  the  file  was  never  written,  it  is 
given  a  length  of  0.  If  this  length  is  less  than  the  size  of  the  area 
which  was  allocated  at  .ENTER  time,  the  unused  blocks  are  reclaimed  as 
an  empty  area  on  the  device. 


Errors : 

.CLOSE  does  not  return  any  errors.  If  the  device  handler  for  the 
operation  is  not  in  memory,  a  fatal  monitor  error  is  generated. 

Example : 

An  example  which  illustrates  the  .CLOSE  request  follows  the  discussion 
of  the  .WRITW  request  in  Section  9.4.47. 
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.CMKT 


9.4.5  .CMKT  (F/B  only) 

The  .CMKT  request  causes  one  or  more  outstanding  mark  time  requests  to 
be  cancelled  (mark  time  requests  are  discussed  In  Section  9.4.22). 

Macro  Call:  .CMKT  .area,  .id,  .time 

where:  .id  is  a  number  used  to  identify  the  request  to  be 

cancelled.  If  .id  is  not  equal  to  0,  the  mark 
time  request  with  that  identifying  number  is 
cancelled.  If  more  than  one  mark  time  request 
has  the  same  .id,  that  with  the  earliest 
expiration  time  is  cancelled.  If  .id  «  0,  all 
mark  time  requests  for  the  issuing  job  are 
cancelled. 

.time  is  the  pointer  to  a  two-word  area  in  which  the 
Monitor  will  return  the  amount  of  time 

remaining  in  the  cancelled  request.  The  first 
word  contains  the  high-order  time,  the  second 
contains  the  low-order.  If  an  address  of  0  is 
specified,  no  value  is  returned.  If  .id  =  0, 
the  .time  parameter  is  ignored  and  need  not  be 
indicated. 


Request  Format: 

R0  4  .area: 


23 


.id 

.time 


Notes : 


1.  Cancelling  a  mark  time  request  frees  the  associated  queue 
element  for  other  uses. 

2.  A  mark  time  request  can  be  converted  into  a  timed  wait  by 
issuing  a  .CMKT  followed  by  a  .TWAIT,  and  specifying  the  same 
.time  area. 

Errors : 


Code  Explanation 

0  The  .id  was  not  zero;  a  mark  time  with  that 

identification  number  could  not  be  found  (implying 
that  the  request  was  never  issued  or  that  it  has 
already  expired) . 
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Example : 

See  the  example  following  the  description  of  the  .MRKT  request. 


.CNTXSW 


9.4.6  .CNTXSW  (F/B  only) 

A  context  switch  is  an  operation  performed  when  a  transition  is  made 
from  running  one  job  to  running  the  other.  The  .CNTXSW  request  is 
used  to  specify  locations  to  be  included  in  the  context  switch. 


Macro  Call:  .CNTXSW  .area,  .addr 

where:  .addr  is  a  list  of  addresses  terminated  by  a  zero 

word.  The  addresses  in  the  list  must  be  even 
and: 


a. 

b. 

c. 


Request  Format: 


RO  $  .area: 


33  0 


.addr 


in  the  range  2-476,  or 
in  the  user  job  area,  or 
in  the  I/O  page  (addresses 
160000-177776) . 


The  system  always  saves  the  parameters  it  needs  to  uniquely  identify 
and  execute  a  job,  including  all  registers,  and  the  locations: 

34/36  Vector  for  TRAP  instruction 
40-52  System  Communication  Area 

If  an  .SFPA  request  (Section  9.4.37)  has  been  executed  with  a  non-zero 
address,  all  floating  point  registers  and  the  floating  point  status 
are  also  saved. 

It  is  possible  that  both  jobs  may  want  to  share  the  use  of  a 
particular  location  and  that  location  is  not  included  in  normal 
context  switch  operations.  For  example,  if  a  program  uses  the  IOT 
instruction  to  perform  some  internal  user  function  (such  as  print 
error  messages) ,  it  must  set  up  the  vector  at  20  and  22  to  point  to  an 
internal  IOT  trap  handling  routine.  If  both  foreground  and  background 
wish  to  use  IOT,  the  IOT  vector  must  always  point  to  the  proper 
location  for  the  job  which  is  executing.  Including  locations  20  and 
22  in  the  .CNTXSW  list  for  both  jobs  will  accomplish  this. 

If  .CNTXSW  is  issued  more  than  once,  only  the  latest  list  is  used; 
the  previous  address  list  is  discarded.  Thus,  all  addresses  to  be 
switched  must  be  included  in  one  list.  If  the  address  (.addr)  is 
zero,  no  extra  locations  are  switched.  The  list  may  not  be  in  an  area 
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into  which  the  USR  swaps,  nor  may  it  be  modified  while  a  job  is 
running. 

Errors : 

Code  Explanation 

0  One  or  more  of  the  above  conditions  was  violated. 

Example  t 

In  this  example,  .CNTXSW  request  is  used  to  specify  that  locations  20 
and  22  (IOT  vector)  and  certain  necessary  EAE  registers  be  context 
switched.  This  allows  both  jobs  to  use  IOT  and  the  EAE  simultaneously 
yet  independently. 


, MCALL 

. , V2 . . , .REGOEP , 

.CNTXSW, .PRINT, .EXIT 

. . V2 . . 

f CALL  FOR  V2  MACROS 

.  REGDEF 

I0EFINE  REGISTERS 

START  1 

MQV 

#LIST,R0 

1  SET  R0  TO  OUR  OWN  LIST 

.CNTXSW 

, iSNAPLS 

1  THE  LIST  OF  ADDRS  IS 

1  AT  SNARLS, 

sec 

IS 

.PRINT 

•AODERR 

IA00RESS  ERROR (SHOULD 
I0CCUR) 

NOT 

.EXIT 

1SI 

.PRINT 

.EXIT 

SCNTOK 

SNARLS  t 

.WORD 

20 

f  ADDRESSES  TO  INCLUDE 

IN  LIST 

.WORD 

22 

.  WORD 

177302 

.WORD 

177304 

.WORD 

177310 

.WORD 

0 

LISTI 

.BYTE 

0.33 

fFUNCTION  CODE  N0R0 

.WORD 

0 

ITHE  MACRO  FILLS  THIS 

ONE. 

ADOERRI 

. ASCI Z 

/ADDRESSING  ERROR/ 

.EVEN 

CNTOKJ 

. ASCIZ 

/CONTEXT  SWITCH 

0  §  K  «  / 

.EVEN 

.END 

START 

.CSIGEN 


9.4.7  .CSIGEN 

The  .CSIGEN  request  calls  the  Command  String  Interpreter  (CSI)  in 
general  mode  to  process  a  standard  RT-11  command  string  (see  Chapter  2 
for  the  description  of  a  standard  command  string).  In  general  mode, 
all  file  .LOOKUPS  and  .ENTERS  as  well  as  handler  .FETCHs  are 
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performed.  When  called  in  general  mode,  the  CSI  closes  channels  0-10 
(octal) . 

Macro  Call:  .CSIGEN  .devspc,  .defext,  .cstring 


where:  .devspc  is  the  address  of  the  memory  area  where  the 

device  handlers  (if  any)  are  to  be  loaded. 

.defext  is  the  address  of  a  four-word  block  which 
contains  the  RAD50  default  extensions.  These 
extensions  are  used  when  a  file  is  specified 
without  an  extension. 


.cstring  is  the  address  of  the  ASCIZ  input  string  or  a 
#0  if  input  is  to  come  from  the  console 
terminal.  (In  a  F/B  environment  only,  if  the 
input  is  from  the  console  terminal,  an 
.UNLOCK  of  the  USR  is  automatically 
performed,  even  if  the  USR  is  locked  at  the 
time.)  If  the  string  is  in  memory,  it  must 
not  contain  a  <CRXLF>,  but  must  terminate 
with  a  zero  byte.  If  the  .cstring  field  is 
left  blank,  input  is  automatically  taken  from 
the  console  terminal. 


.CSIGEN  loads  all  necessary  handlers  and  opens  the  files  as  specified. 
The  area  specified  for  the  device  handlers  must  be  large  enough  to 
hold  all  the  necessary  handlers  simultaneously.  If  the  device 
handlers  exceed  the  area  available,  the  user  program  may  be  destroyed. 
The  system,  however,  is  protected  from  this. 

When  the  EMT  is  complete,  register  0  points  to  the  first  available 
location  above  the  handlers. 


The  four-word  block  pointed  to  by  .defext  is  arranged  as: 

Word  1:  default  extension  for  all  input  channels 

Words  2, 3, and  4:  default  extensions  for  output  channels  0,1,2 

respectively 

If  there  is  no  default  for  a  particular  position,  the  associated  word 
must  contain  a  zero.  All  extensions  are  expressed  in  Radix  50.  For 
example,  the  following  block  can  be  used  to  set  up  default  extensions 
for  a  macro  assembler: 


DEFEXT:  . RAD50  "MAC" 

. RAD50  "OBJ" 
. RAD50  "LST" 
.WORD  0 

In  the  command  string: 


*DT0 : ALPHA, DTI :BETA=DT2 : INPUT 

the  default  extension  for  input  is  MAC;  for  output,  OBJ  and  LST.  If 
no  =  sign  is  present,  input  is  assumed. 

When  control  returns  to  the  user  program  after  a  call  to  .CSIGEN,  all 
the  specified  files  have  been  opened  for  input  and/or  output.  The 
association  is  as  follows:  the  three  possible  output  files  are 
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assigned  to  channels  0,  1,  and  2;  the  six  input  slots  are  assigned  to 
channels  3  through  10.  A  null  specification  causes  the  associated 
channel  to  remain  inactive.  For  example,  in  the  following  strings 

*,LP:=F1,F2 

channel  0  is  inactive  since  the  first  slot  is  null.  Channel  1  is 
associated  with  the  line  printer,  and  channel  2  is  inactive.  Channels 
3  and  4  are  associated  with  two  files  on  DKs,  while  channels  5  through 
10  are  inactive.  The  user  program  can  determine  whether  a  channel  is 
inactive  by  issuing  a  .WAIT  request  on  the  associated  channel,  which 
returns  an  error  if  the  channel  is  not  open. 


Switches  and  their  associated  values  are  returned  on  the  stack;  see 
Section  9.4. 8.1  for  a  description  of  the  way  switch  information  is 
passed. 

Errors  t 


If  CSI  errors  occur  and  input  was  from  the  console  terminal,  an  error 
message  describing  the  fault  is  printed  on  the  terminal  and  the  CSI 
retries  the  command  (these  messages  appear  in  Section  9. 4. 8.1).  If  the 
input  was  from  a  string,  the  carry  bit  is  set  and  byte  52  contains  the 
error  code.  The  errors  are: 

Code  Explanation 

0  Illegal  command  (bad  separators,  illegal  filename, 

command  too  long,  etc.). 

1  A  device  specified  is  not  found  in  the  system  tables. 


2  Unused. 

3  An  attempt  to  .ENTER  a  file  failed  because  of  a  full 
directory. 

4  An  input  file  was  not  found  in  a  .LOOKUP. 

Example : 

This  example  uses  the  general  mode  of  the  CSI  in  a  program  to  copy  an 
input  file  to  an  output  file.  Command  input  to  the  CSI  is  from  the 
console  terminal. 


.MCALb 
•  *  V2,  • 

. REGDEF 

•  •  V2 , • , , REGOEF 

.  mcall 

ERRWD«52 

.CSIGEN, .READW, 

STARTI  .CSIGEN 

PDSPACE , PDEXT 

MOV 

R0 , BUFF 

CLR 

INBLK 

MOV 

PLIST, R5 

REAOI  .READW 

R5, *3, BUFF, *256 

BCC 

2S 

T8TB 

PPERRWD 

BEQ 

EOF 

MOV 

ilNERR, R0 

PRINT, .EXIT, .WRIT W, .CLOSE, .SRESET 


I  GET  STRING  FROM  TERMINAL 
I R0  HAS  FIRST  FREE  LOCATION 
I  INPUT  BLOCK  i 
IEMT  ARGUMENT  LIST 
, INBLK  » READ  CHANNEL  3 
»N0  ERRORS 
f  EOF  ERROR? 
f  YES 
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ISI 

.PRINT 

(  ERROR  ME8SAEE 

CLR 

R0 

1  HARO  EXIT 

.EXIT 

291 

, WRITW 

R5,#0, BUFF, #256 

i # INBLK  I  WRITE  THE  BLOCK 

BCC 

NOERR 

INO  ERROR  WRXTXN6 

MOV 

PWTERR , R0 

BR 

1$ 

1  HARO  OUTPUT  ERROR 

NOERRl 

INC 

XNBLK 

IGET  NEXT  BLOCK 

BR 

READ 

(  LOOP  UNTIL  DONE 

EOF  1 

.CLOSE 

#0 

f CLOSE  OUTPUT  CHANNEL 

.CLOSE 

#3 

|AN0  INPUT  CHANNEL 

.SRESET 

(RELEASE  HANDLER  FROM  MEMORY 

BR 

START 

(60  FOR  NEXT  COMMAND  LINE 

OEXTl 

.W0R0 

0,  0, 0, 0 

(NO  DEFAULT  EXTENSIONS 

BUFFI 

.WORD 

0 

(I/O  BUFFER  START 

XNBIKI 

.WORD 

0 

(RELATIVE  BLOCK  TO  RE AD/WRXTE 

LIST! 

.BLKW 

5 

(EMT  ARGUMENT  LIST 

INERRl 

.  A3CXZ 

/INPUT  ERROR/ 

.EVEN 

WTERRI 

.ASCII 

/OUTPUT  ERROR/ 

.EVEN 

DSPACE* 

• 

(HANDLER  SPACE 

.END 

START 

In  the  Command  String  Interpreter's  general  mode,  the  .CLOSES  on 
channels  0  and  3  are  not  absolutely  necessary  since  the  CSI  .CLOSES 
channels  0-8  when  it  is  called.  However,  if  .CSISPC  is  used,  or  if 
the  line  is  not  obtained  using  the  CSI  at  all,  the  .CLOSE  calls  are 
required. 


.CSISPC 


9.4.8  .CSISPC 

The  .CSISPC  request  calls  the  Command  String  Interpreter  in  special 
mode  to  parse  the  command  string  and  return  file  descriptors  and 
switches  to  the  program.  In  this  mode,  the  CSI  does  not  perform  any 
handler  fetches,  .CLOSES,  .ENTERS,  or  .LOOKUPS. 

Macro  Call:  .CSISPC  .outspc,  .defext,  .cstring 

where:  .outspc  is  the  address  of  the  39-word  block  to 

contain  the  file  descriptors  produced  by 
.CSISPC.  This  area  may  overlay  the  space 
allocated  to  .cstring  if  desired. 

.defext  is  the  address  of  a  four-word  block  which 

contains  the  RAD50  default  extensions.  These 
extensions  are  used  when  a  file  is  specified 
without  an  extension. 
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.cstring  is  the  address  of  the  ASCIZ  input  string  or  a 
#0  if  input  is  to  come  from  the  console 
terminal.  If  the  string  is  in  memory,  it 
must  not  contain  a  <CRXLF>  but  must 
terminate  with  a  zero  byte.  If  .cstring  is 
blank,  input  is  automatically  taken  from  the 
console  terminal. 

The  39-word  file  description  consists  of  nine  file  descriptor  blocks 
(five  words  for  each  of  three  possible  output  files;  four  words  for 
each  of  six  possible  input  files)  which  correspond  to  the  nine 
possible  files  (three  output,  six  input) .  If  any  of  the  nine  possible 
filenames  are  not  specified,  the  corresponding  descriptor  block  is 
filled  with  zeroes. 

The  five-word  blocks  hold  four  words  of  RAD50  representing 
devsfile.ext,  and  1  word  representing  the  size  specification  given  in 
the  string.  (A  size  specification  is  a  decimal  number  enclosed  in 
square  brackets  [] ,  following  the  output  file  descriptor.)  For 
example , 

*DT3 s  LIST . MAC [ 15 ] =PR : 

Using  special  mode,  the  CSI  returns  in  the  first  five  word  slot: 

16101  .RAD50  for  DT3 

46173  .RAD50  for  LIS 

76400  .RAD50  for  T 

50553  .RAD50  for  MAC 

00017  Octal  value  of  size  request 

In  the  fourth  slot  (starting  at  an  offset  of  36  (octal)  bytes  into 
.outspc) ,  the  CSI  returns: 

63320  .RAD50  for  PR 

0  No  file  name 

0  Specified 

0 

Since  this  is  an  input  file,  only  four  words  are  returned. 

Switches  and  their  associated  values  are  returned  on  the  stack.  See 
Section  9. 4. 8.1. 

Errors : 

Errors  are  the  same  as  in  general  mode.  However,  since  .LOOKUPS  and 
.ENTERS  are  not  done,  the  error  codes  which  are  valid  are: 

Code  Explanation 

0  Illegal  command  line 

1  Illegal  device 


Example : 

This  example  illustrates  the  use  of  the  special  mode  of  CSI.  This 
example  could  be  a  program  to  read  a  file  which  is  not  in  RT-11  format 
to  a  file  under  RT-11. 


9-37 


7 


Programmed  Requests 


.MCALL 

,.V2.. 

.REGDEF 

.MCALL 


..V2,., .REGOEP 


, CSI SPC, .PRINT, .EXIT, .ENTER, .CLOSE 


STARTI 

•CSI8PC 

•OUTSPC , POEXT , 

PCSTRNG  f GET  INPUT  FROM  A 

1  STRING  IN  MEMORY 

sec 

28 

MOV 

•8VNERR, R0 

(SYNTAX  ERROR 

IS* 

.PRINT 

.EXIT 

(ERROR  MESSAGE 

2SI 

.ENTER 

#LIST,#0,#OUTSPC,*M.  1  ENTER  FILE  UNDER  RT-ii 

sec 

SS 

MOV 

•ENMSG, R0 

(ENTER  FAILED 

SR 

IS 

SSI 

JSR 

RS, INPUT 

(ROUTINE  INPUT  RILL  USE 
(THE  INFORMATION  AT 
( POUTSPC+Sfe  TO  READ  INPUT 
(FROM  THE  NON-RTll  DEVICE. 
(INPUT  IS  PROCESSED  AND 
(WRITTEN  VIA  .WRITW  REQUESTS 

.CLOSE 

#0 

(MAKE  OUTPUT  FILE  PERMANENT 

.EXIT 

(AND  EXIT  PROGRAM 

CSTRNGI 

•ASCIZ 

"DT4IRTFIL,MAC»DT2»00S,MAC" 

.EVEN 

OEXTI 

.WORD 

0, 0 , 0, 0 

(NO  DEFAULT  EXTENSIONS 

LISTI 

.BLKR 

S 

(LIST  FOR  EMT  CALLS 

SYNERRI 

.ASCIZ 

"CSI  ERROR" 

ENMSGl 

,  ASCIZ 
.EVEN 

"ENTER  FAILED" 

INPUTl 

RTS 

RS 

OUTSPC* 

• 

(CSI  LIST  GOES  HERE 

.END 

START 

9. 4. 8.1  Passing  Switch  Information 

In  both  general  and  special  modes  of  the  CSI ,  switches  and  their 
associated  values  are  returned  on  the  stack.  A  CSI  switch  is  a  slash 
(/)  followed  by  any  character.  The  CSI  does  not  restrict  the  switch 
to  printing  characters,  although  it  is  suggested  that  printing 
characters  be  used  wherever  possible.  The  switch  can  be  followed  by 
an  optional  value,  which  is  indicated  by  a  s  or  1  separator.  The  : 
separator  is  followed  by  either  an  octal  number  or  by  one  to  three 
alphanumeric  characters,  the  first  of  which  must  be  alphabetic,  which 
are  converted  to  Radix— 50.  The  t  separator  is  followed  by  a  decimal 
value.  Switches  can  be  associated  with  files  with  the  CSI.  For 
example : 

*DK s  FOO/A, DT4  s  FILE . OBJ/A  s 10  0 

In  this  case,  there  are  two  A  switches.  The  first  is  associated  with 
the  input  file  DKsFOO.  The  second  is  associated  with  the  input  file 
DT4 :FILE. OBJ,  and  has  a  value  of  100(8).  The  stack  output  of  the  CSI 
is  as  follows: 
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Word  #  Value 


Meaning 


1  N 

(top  of 
stack) 


Number  of  switches  found  in 
command  string.  If  N=0 ,  no  switches 
were  found. 


2 


3 


Switch  value 
and  file  number 


Switch  value 
or  next  switch 


Even  byte  *  7— bit  ASCII  switch  value. 

Bits  8-14  =  Number  (0-10)  of  the  file 
with  which  the  switch  is 
associated. 

Bit  15  =  1  if  the  switch  had  a 

value . 

■  0  if  the  switch  had  no 

value . 

If  word  2  was  less  than  0,  word  3  » 
switch  value.  If  word  2  was 
greater  than  0,  this  word  is  the 
next  switch  value  (if  it  exists). 


For  example ,  if  the  input  to  the  CSI  iss 

*FILE/B :  20  ,  FIL2/E-DT3 : INPUT/X : SY  s  20 


on  return,  the  stack  is: 
Stack  Pointer— » 


3 

101530 

20 

101530 


Three  switches  appeared. 


Last  8witch=X; 
value. 

with 

file 

3,  has 

a 

Value  of  switch 

X=20 

Next  switch  **X; 
value. 

with 

file 

3,  has 

a 

Next  value  of  switch 

X-RAD50 

code 

for 

SY. 

Next  switch»E;  associated  with  file  1, 
no  value. 

Switch“B;  associated  with  file  0  and 
has  a  value. 

Value  is  20* 


As  an  extended  example,  assume  the  following  string  was  input  for  the 
CSI  in  general  mode: 


*FILE [8] ,LP: ,SY: FILE2 [20 ] =PR: ,DT1 : IN1/B ,DT2 : IN2/M: 7 


Assume  also  that  the  default  extension  block  is: 


DEFEXT:  . RAD50  'MAC' 

. RAD50  'OP1' 

. RAD50  ' OP2' 

.RAD50  'OP3' 


j INPUT  EXTENSION 
; FIRST  OUTPUT  EXTENSION 
; SECOND  OUTPUT  EXTENSION 
; THIRD  OUTPUT  EXTENSION 


The  result  of  this  CSI  call  would  be: 


1.  A  file  named  FILE.OP1  is  entered  on  channel  0  on  device  DK; 
channel  1  is  open  for  output  to  the  device  LP;  a  20-block 
file  named  FILE2.0P3  is  entered  on  the  system  device  on 
channel  2. 
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2.  Channel  3  is  open  for  input  from  paper  tape;  channel  4  is 
open  for  input  from  a  file  INI. MAC  on  device  DTI;  channel  5 
is  open  for  input  from  IN2.MAC  on  device  DT2. 

3.  The  stack  contains  switches  and  values  as  follows: 

Explanation 


2  switches  found  in  string. 

Second  switch  is  M,  associated  with 
Channel  5;  has  a  numeric  value. 
Numeric  value  is  7. 

Switch  is  B ,  associated  with 
Channel  4;  has  no  numeric  value. 

If  the  CSI  were  called  in  special  mode  (Section  9.4.8)  ,  the  stack 
would  be  the  same  as  for  the  general  mode  call,  and  the  descriptor 
table  would  contain: 


15270 

; . RAD50 

'DK' 

23364 

; . RAD50 

•FIL' 

17500 

; . RAD50 

•  e* 

60137 

; .RAD50 

'0P1' 

10 

; LENGTH 

OF  8  BLOCKS 

46600 

; . RAD50 

'LP' 

0 

;N0  NAME 

:  OR  LENGTH  SPECIFIED 

0 

0 

0 

75250 

; . RAD50 

•SY' 

23364 

; . RAD 50 

'FIL' 

22100 

;  . RAD50 

•E2‘ 

60141 

;  . RAD50 

•OP3' 

24 

; LENGTH 

OF  20  (DECIMAL) 

63320 

; . RAD50 

'PR' 

0 

0 

0 

16077 

; . RAD50 

'DTI' 

35217 

; . RAD50 

•INI' 

0 

; . RAD50 

•  • 

50553 

; . RAD50 

•MAC' 

16100 

; . RAD50 

•DT2' 

35220 

; . RAD50 

•IN2* 

0 

;  . RAD50 

•  • 

50553 

; . RAD50 

•mac' 

0 

• 

• 

• 

0 

(twelve 

more  zero  words 

are  returned) 


2 

102515 

7 

2102 


Keyboard  error  messages  which  may  occur  from  incorrect  use  of  the  CSI 
when  input  is  from  the  console  keyboard  include: 


Message 


Meaning 


?ILL  CMD?  Syntax  error. 

?FIL  NOT  FND?  Input  file  was  not  found. 
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?DEV  FUL?  Output  file  will  not  fit. 

?ILL  DEV?  Device  specified  does  not  exist. 


Notes : 

1.  In  many  cases,  the  user  program  does  not  need  to  process 
switches  in  CSI  calls.  However,  the  user  at  the  console  may 
inadvertently  enter  switches.  In  this  case,  it  is  wise  for 
the  program  to  save  the  value  of  the  stack  pointer  before  the 
call  to  the  CSI,  and  restore  it  after  the  call.  In  this  way, 
no  extraneous  values  will  be  left  on  the  stack. 

2.  In  the  F/B  System,  calls  to  the  CSI  which  require  console 
terminal  input  will  always  do  an  implicit  .UNLOCK  of  the  USR. 
This  should  be  kept  in  mind  when  using  .LOCK  calls. 


.CSTAT 


9.4.9  .CSTAT  (F/B  only) 

This  request  furnishes  the  user  with  information  about  a  channel.  It 
is  supported  only  in  the  F/B  environment;  no  information  is  returned 
in  the  Single-Job  Monitor. 

Macro  Call:  .CSTAT  .area,  .chan,  .addr 

where:  .addr  is  the  address  of  a  6-word  block  which  is  to 

contain  the  status 


Request  Format: 


RO  4 


.area: 


27 

•  chan 

•  addr 

The  6  words  passed  back  to  the  user  are: 

1.  Channel  status  word  (see  Section  9.4.34) 

2.  Starting  block  number  of  file 

3.  Length  of  file 

4.  Highest  block  written  since  file  was  opened 

5.  Unit  number  of  device  with  which  this  channel  is  associated 

6.  RAD50  of  the  device  name  with  which  the  channel  is  associated 
(this  is  a  physical  device  name,  unaffected  by  any  user  name 
ASSIGNment  in  effect) 

The  fourth  word  (highest  block)  is  maintained  by  the  .WRITE  requests. 
If  data  is  being  written  on  this  channel,  the  highest  relative  block 
number  is  kept  in  this  word. 
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Errors : 

Code  Explanation 

0  The  channel  is  not  open. 

Example : 

In  this  example,  .CSTAT  is  used  to  determine  the  .RAD50  representation 
of  the  device  with  which  the  channel  is  associated. 


• MC  ALL 

..V2.., .REGDEF,. 

CSIGEN, .CSTAT 

•  • V2 , , 
.REGDEF 

, MC  ALL 

.PRINT, .EXIT 

STI 

.CSIGEN 

PDEVSDC, PDEFEXT 

I0PEN  FILES 

.CSTAT 

iAREA, #0, PADDR 

1  GET  THE  STATUS 

BCS 

NOCHAN 

ICHANNEL  0  NOT  OPEN 

MOV 

f ADOR+10»  R5 

1  POINT  TO  UNIT  # 

MOV 

(R5)*,R0 

> UNIT  •  TO  R0 

ADO 

(PC) ♦, R0 

(MAKE  IT  RAD50 

.RAD50 

/  0/ 

ADD 

(R5),R0 

> GET  OEVICE  NAME 

MOV 

.EXIT 

R0i OEVNAM 

PDEVNAM  HAS  RADS0  DEVICE 

AREA  1 

.BLKM 

5 

IEMT  ARG  LIST 

ADDRl 

,8LK* 

6 

1  ARE A  FOR  CHANNEL  STATUS 

DEVNAMI 

.NORD 

0 

1  STORAGE  FOR  DEVICE  NAME 

DEFEXTl 

,  NORD 

0 1  0 t 0 ,  0 

NOCHANI 

.PRINT 

.EXIT 

•MSG 

MSG  1 

.ASCIZ 

/NO  OUTPUT  FILE/ 

.EVEN 

DEVSDC* 

• 

.END 

BT 

.DELETE 


9.4.10  . DELETE 

The  .DELETE  request  deletes  a  named  file  from  an  indicated  device 
Macro  Call:  .DELETE  .area,  .chan,  .dblk,  .count 
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where:  .count  is  used  by  magtape/cassette  only,  (Refer  to 

Appendix  H  for  more  information  concerning 
the  magtape  and  cassette  handlers.) 


Request  Format: 


RO  4  .area: 


.chan 


,dblk 

.count 


Note: 

The  channel  specified  in  the  .DELETE  request  must  not  be  in  use  when 
the  request  is  made,  or  an  error  will  occur.  The  file  is  deleted  from 
the  device,  and  an  empty  (UNUSED)  entry  of  the  same  size  is  put  in  its 
place.  A  .DELETE  issued  to  a  non-file  structured  device  is  ignored. 
.DELETE  requires  that  the  handler  to  be  used  be  in  memory  at  the  time 
the  request  is  made.  When  the  .DELETE  is  complete,  the  specified 
channel  is  left  inactive. 

Errors : 

Code  Explanation 

0  Channel  is  active 

1  File  was  not  found  in  the  device  directory 

Example : 

This  example  uses  the  special  mode  of  CSI  to  delete  files. 

.MCALL  ,,V2,,,.REGDEF 

. , V2, , 

• REGOEF 

.MCAIL  .SRESET,.CSI3PC,  .DELETE,,  PRINT,  .EXIT 

START!  .SRESET  ! MAKE  SURE  CHANNELS 

I  ARE  FREE 

.CSISPC  POUTSPC'POEFEXT  f GET  COMMAND  LINE 


I  TERMINAL  DIALOG  MAS 
IDTIPILE 


.DELETE 

•  LIST  , #0» 

•  INSPC  1  USE  CHANNEL  0  TO 

fOELETE  THE  FILE 

1  WHICH  IS  AT  THE 
IFIR8T  INPUT  SLOT, 

sec 

START 

I0K,  LOOP  AGAIN 

.PRINT 

•NOFILE 

INO  SUCH  FILE 

SR 

START 

NOPILEI 

.ASCXZ 

.EVEN 

/FILE  NOT 

FOUND/ 

OEPEXTI 

.RA050 

/MAC/ 

1 .MAC  INPUT  EXTENSION 

.WORD 

0,0,0 

INO  OUTPUT  DEFAULTS 

LIST! 

.BLKW 

2 

IEMT  ARG  LIST 

OUTSPCa 

• 

INSPC* . 

*36  ' 

.  BLKW 

39. 

,EN0 

START 

INSPC  is  the  address  of  the  first  input  slot  in  the  CSI  input  table. 
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.DEVICE 


9.4.11  .DEVICE  (F/B  Only) 


This  request  allows  the  user  to  set  up  a  list  of  addresses  to  be 
loaded  with  specified  values  when  a  program  is  terminated.  Upon  an 
.EXIT  or  CTRL  C,  this  list  is  picked  up  by  the  system  and  the 
appropriate  addresses  are  set  up  with  the  corresponding  values.  This 
function  is  primarily  designed  to  allow  user  programs  to  load  device 
registers  with  necessary  values •  In  particular  ,  it  is  used  to  turn 
off  a  device's  interrupt  enable  bit  when  the  program  servicing  the 
device  terminates. 


Macro  Call: 
where: 


.DEVICE  .area,  .addr 

. addr  is  the  address  of  the  list  of  masks  and 

words . 


Request  Format: 

RO  4 


area: 


14 

0 

.addr 

The  list  is  composed  of  address/value  pairs  and  should  be  terminated 
by  a  0  address.  Only  one  list  can  be  active  at  a  given  time.  If 
multiple  .DEVICE  requests  are  given,  the  last  list  specified  is  the 
one  used. 


Note: 

When  the  job  is  terminated  for  any  reason,  the  list  is  scanned  once. 
At  that  point,  the  monitor  disables  the  feature  until  another  .DEVICE 
call  is  executed.  Thus,  background  programs  which  are  re-enterable 
should  include  .DEVICE  as  a  part  of  the  reenter  code. 

Errors : 

None. 

Example : 

The  following  example  shows  how  .DEVICE  is  used  to  disable  interrupts 
from  the  AFC11  (A-D  converter  sub-system) . 

, MC ALL  •  •  V 2 « . #  .  RE GDE F 

• • V2. « 

.REGOEF 

.MCALL  .DEVICE#  .EXIT 

.DEVICE  *LI9T 
.EXIT 

.BYTE  0*14  >EMT  ARG  LIST 


STARTI 

LIST! 
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.WORD  ATOD 

ATODI  172570  I  ADDRESS  13  172570 

0  I  JAM  A  0  INTO  IT 

0  >  THIS  0  TERMINATES  THE  LIST. 

.END  START 


.DSTATUS 


9.4.12  .DSTATUS 

This  request  is  used  to  obtain  information  about  a  particular  device. 
Macro  Call:  .DSTATUS  .cblk,  .devnam 

where:  .cblk  is  the  4-word  space  used  to  store  the  status 

information. 

.devnam  is  the  pointer  to  the  RAD50  device  name. 

.DSTATUS  looks  for  the  device  specified  by  .devnam  and,  if  found, 
returns  four  words  of  status  starting  at  the  address  specified  by 
•cblk.  The  four  words  returned  are: 

1.  Status  Word 

Bits  7-0:  contain  a  number  which  identifies  the  device  in 
question.  The  values  (octal)  currently  defined 
are: 

0  =  RK05  Disk 

1  =  TC11  DECtape 

2  ■  Unused 

3  =  Line  Printer 

4  ■  Console  Terminal  (LT33,  LT35,  LA30, 

LA36,  \rT05,  VT50) 

5,6  =  Unused 

7  =  PC11  High-speed  Reader 

10  =  PC11  High-speed  Punch 

11  =  Magtape 

12  =  RF11  Disk 

13  =  TA11  Cassette 

14  =  Card  Reader 


Bit  15: 

Bit  14: 
Bit  13: 
Bit  12: 


1=  Pile  structured  device  (disk,  DECtape) 
0“  Non-file  device 
1=  Read-only  device 
1=  Write-only  device 

1=  Device  whose  directory  is  not  an  RT-11 
directory  (magtape,  cassette). 
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2.  Handler  size. 

The  size  of  the  device  handler,  in  bytes. 

3.  Entry  point. 

Non-zero  implies  the  handler  is  now  in  memory?  zero 
implies  it  must  be  .FETCHed  before  it  can  be  used. 

4.  Device  size. 

The  size  of  the  device  (in  256-word  blocks)  for  file 
structured  devices?  zero  for  non— file  devices. 

The  device  name  may  be  a  user-assigned  name. 


Errors  s 

Code  Explanation 

0  Device  not  found  in  tables. 

Example : 

This  example  shows  how  to  determine  if  a  particular  device  handler  is 
in  memory  and,  if  it  is  not,  how  to  .FETCH  it  there. 


.MCALL  ..V2..,.REGDEF 
..V2,. 

• REGDEF 

.MCALL  .DSTATUS, .PRINT, .EXIT,, FETCH 


START! 

IS! 


21 1 

CORE! 

PPTRI 

FEFAILI 

ILLOEVI 

FECHOKI 

HNDLR*  • 


.DSTATUS 
BCC 

.PRINT 
.EXIT 
T8T 
BNE 

.FETCH 

sec 

.PRINT 
.EXIT 
.PRINT 
.EXIT 
.8LKW 
.RAD50 
.RAD90 
,  ASCIZ 
« ASCIZ 
.EVEN 
.ASCIZ 
.EVEN 

.END 


FCORE , FFPTR 

IS 

FILLDEV 

C0RE*« 

2S 

FHNDLR, FFPTR 
28 

FFEFAIL 

FFECHOK 


IGET  STATUS  OF  DEVICE 
IDEVICE  NOT  IN  TABLES 
IIS  DEVICE  RESIDENT? 
INO,  GET  IT 
IFETCH  FAILED 


A  I0SATUS  GOES  HERE 

/DT0/  IDEVICE  NAME 

/file  HAC/  IFILE  NAME 
/FETCH  FAILED/ 

/ILLEGAL  DEVICE/ 

/FETCH  O.K,/ 

IHANDLER  HILL  60  HERE 

START 
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.ENTER 


9.4.13  .ENTER 

The  .ENTER  request  allocates  space  on  the  specified  device  and  creates 
a  tentative  entry  for  the  named  file.  The  channel  number  specified  is 
associated  with  the  file. 

Macro  Call:  .ENTER  .area,  .chan,  .dblk,  .length,  .count 


where:  .length  is  the  file  specification.  The  file 

allocation  is  as  follows: 

0  -  either  1/2  the  largest  empty  segment  or 
the  entire  second  largest  segment, 
whichever  is  largest.  (A  maximum  size 
for  non-specific  • ENTERS  may  be  patched 
in  the  monitor.) 

M  -  a  file  of  M  blocks.  M  may  exceed  the 
maximum  mentioned  above. 

-1  -  the  largest  empty  segment  on  the  device. 

.count  file  number  for  magtape/cassette  (see 

Appendix  H) ;  if  this  argument  is  blank,  a 
value  of  zero  is  assumed. 


Request  Format: 


RO  ^  .area: 


2  1 . chan 

.dblk 

. length 

•count 


The  file  created  with  an  .ENTER  is  not  a  permanent  file  until  the 
.CLOSE  on  that  channel  is  given.  Thus,  the  newly  created  file  is  not 
available  to  .LOOKUP  and  the  channel  may  not  be  used  by  .SAVESTATUS 
requests.  However,  it  is  possible  to  go  back  and  read  data  which  has 
just  been  written  into  the  file  by  referencing  the  appropriate  block 
number.  When  the  .CLOSE  to  the  channel  is  given,  any  already  existing 
permanent  file  of  the  same  name  on  the  same  device  is  deleted  and  the 
new  file  becomes  permanent.  Although  space  is  allocated  to  a  file 
during  the  .ENTER  operation,  the  actual  length  of  the  file  is 
determined  when  .CLOSE  is  requested. 

Each  job  may  have  up  to  256  files  open  on  the  system  at  any  time.  If 
required,  all  256  may  be  opened  for  output  with  the  .ENTER  function. 
.ENTER  requires  that  the  device  handler  be  in  memory  when  the  request 
is  made.  Thus,  a  .FETCH  should  normally  be  executed  before  a  .ENTER 
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can  be  done.  On  return,  RO  contains  the  size  of  the  area  actually 
allocated  for  use. 

Notes : 

When  using  the  0  length  feature  of  .ENTER,  it  must  be  kept  in  mind 
that  less  than  the  largest  empty  space  is  allocated.  This  can  have  an 
important  effect  in  transferring  files  between  devices  (particularly 
DECtape)  which  have  a  relatively  small  capacity.  For  example,  to 
transfer  a  200-block  file  to  a  DECtape  on  which  the  largest  available 
empty  space  is  300  blocks,  a  0  length  transfer  will  not  work.  Since 
the  .ENTER  allocates  half  the  largest  space,  only  150  blocks  are 
really  allocated  and  an  output  error  will  occur  during  the  transfer. 
If  a  specific  length  of  200  is  requested,  however,  the  transfer  will 
proceed  without  error. 

Errors : 

Code  Explanation 

0  Channel  is  in  use. 

1  In  a  fixed  length  request,  no  space  greater 

than  or  equal  to  N  was  found,  or  in  a 
non-specific  request  the  device  or  the 
directory  was  found  to  be  empty. 


Example: 

•ENTER  may  be  used  to  open  a  file  on  a  specified  device,  and  then 
write  data  from  memory  into  that  file  as  follows: 


•  MC  ALL 

. .  V2. . , .REG0EF , 

.  ENTER,. WRITW, .CLOSE , .PRINT 

.MCALL 

•  ■  V  2 1  § 

•  RE60EF 

.SRESET, .EXIT, . 

FETCH 

STARTl 

,  SRESET 

IMAKE  SURE  ALL  CHANNELS 

1  ARE  CLOSED. 

.FETCH 

PCQRSPC , f FPRT 

>  FETCH  DEVICE  HANDLER 

BCS 

BADFET 

>  .FETCH  ERROR,  PROBABLY 

1  ILLEGAL  0EVICE. 

.ENTER 

•AREA,B0,»FPRT 

I0PEN  A  FILE  ON  THE  DEVICE 
>  SPECIFIED.  LENGTH  0  HILL 
>GIVE  1/2  OF  LARGEST  EMPTY 

I  SPACE  NOW  AVAILABLE. 

BCS 

BA0ENT 

IFAILED.  CHANNEL  PROBABLY  BUSY 

.WRIT* 

•ARE A , *0, PBUFF , 

•END-BUFF/2, #0 

J  WRITE  DATA  FROM  MEMORY.  THE 

1  SIZE  IS  #  OF  WORDS  BETWEEN 

1  BUFF  AND  EN0,  START  AT  BLOCK  0, 

BCS 

BA0WRT 

I  WRITE  FAILURE. 

.CLOSE 
•  EXIT 

•  0 

1  CLOSE  THE  FILE 
f  AND  GO  TO  KEYBOARD  MONITOR. 

FPRTl 

.RAD50 

/OK  / 

(FILE  WILL  BE  ON  DK 

.RAO50 

/F ICE  EXT/ 

INAMED  FILE, EXT 

AREA  1 

.BLKW 

10 

IEMT  ARGUMENT  LIST 

BADFETl 

.PRINT 

•  FMSG 
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BADENTI 

.exit 

.PRINT 

PEHSG 

BADWRTI 

.EXIT 

.PRINT 

PWHSC 

FMSGI 

.EXIT 
,  ASCII 

/BAD  FETCH/ 

EMSGI 

•  ASCIZ 

/BAD  ENTER/ 

WMS6I 

.  ASCIZ 

/WRITE  ERROR/ 

C0R8PCI 

.EVEN 

.BUN 

400 

BUFFI 

.REPT 

400 

.WORD 

0*1 

END! 

.ENOR 

.end 

START 

HEAVE  400(e)  WORDS 
IFOR  OEVICE  HANDLER. 

I  THIS  IS  BUFFER  TO  BE  WRITTEN  OUT 


.EXIT 


9.4.14  .EXIT 

The  .EXIT  request  causes  the  user  program  to  terminate.  When  used 
from  a  background  job  under  the  F/B  Monitor  and  when  used  under  the 
Single-Job  Monitor.  .EXIT  causes  KMON  to  run  in  the  background  area. 
All  outstanding  mark  time  requests  are  cancelled.  Any  I/O  requests 
and  completion  routines  pending  for  that  job  are  allowed  to  complete. 
If  part  of  the  background  job  resides  where  KMON  and  USR  are  to  be 
read,  the  user  job  is  written  onto  system  device  scratch  blocks.  KMON 
and  USR  are  then  loaded  and  control  goes  to  KMON  in  the  background 
area.  If  R0=0  when  the  .EXIT  is  done,  an  implicit  INIT  command  is 
executed  when  KMON  is  entered,  disabling  the  subsequent  use  of 
.REENTER,  .START,  or  .CLOSE. 

.EXIT  also  resets  any  .CDFN  and  .QSET  calls  that  were  done  and 
executes  an  .UNLOCK  if  a  .LOCK  has  been  done.  Thus,  the  .CLOSE 
command  from  the  Keyboard  Monitor  does  not  operate  for  programs  which 
perform  .CDFN  requests. 

In  a  F/B  system,  an  .EXIT  from  a  completion  routine  acts  as  if  a 
double  CTRL  C  has  been  typed,  aborting  all  I/O  in  progress  before 
exiting.  In  general,  .EXIT  from  a  completion  routine  should  be 
avoided. 

Macro  Calls  .EXIT 


Errors  s 
None. 
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.FETCH 


9.4.15  .FETCH 


The  • FETCH  request  loads  device  handlers  into  memory  from  the  system 
device. 

Macro  Calls  .FETCH  .coradd,  .devname 

where:  .coradd  is  the  address  where  the  device  handler  is  to 

be  loaded. 

.devname  is  the  pointer  to  the  RAD50  device  name. 


The  storage  address  for  the  device  handler  is  passed  on  the  stack. 
When  the  .FETCH  is  complete,  RO  points  to  the  first  available  location 
above  the  handler.  If  the  handler  is  already  in  memory ,  RO  keeps  the 
same  value  as  was  initially  pushed  onto  the  stack.  If  the  argument  on 
the  stack  is  less  than  400(8),  it  is  assumed  that  a  handler  .RELEAS  is 
being  done.  (.RELEAS  does  not  dismiss  a  handler  which  was #LOADed  from 
the  KMON ;  an  .UNLOAD  must  be  done.)  After  a  .RELEAS,  a  .FETCH  must  be 
issued  in  order  to  use  the  device  again. 

Several  requests  require  a  device  handler  to  be  in  memory  for 
successful  operation.  These  include: 


CLOSE 

LOOKUP 

ENTER 

RENAME 


RE  ADC 
WRITC 
READW 
WRITW 


READ 

WRITE 

SPFUN 

DELETE 


Since  foreground  jobs  must  have  handlers  resident,  a  .FETCH  from  the 
foreground  will  give  a  fatal  error  if  the  handler  has  not  been 
previously  LOADed. 


Errors : 


Code  Explanation 

0  The  device  name  specified  does  not  exist,  or 

there  is  no  handler  for  that  device  in  the 
system. 


Example : 

In  the  following  example,  the  PR  and  PP  handlers  are  fetched  into 
memory  in  preparation  for  their  use  by  a  program.  The  program  sets 
aside  handler  space  from  its  free  memory  area. 
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• MC ALU 
,  ,V2,. 
.RE6DEF 

• , V2 . . ,  . REGDEF , 

.FETCH, .PRINT, .EXIT 

STARTl 

.FETCH 

FREE , PPRNAME 

IFETCH  PR  HANDLER 

BCS 

FERR 

IFETCH  ERROR 

MOV 

R0,R2 

.FETCH 

R2 , PPPNAMI 

IFETCH  PP  HANDLER 

I  IMMEDIATELY  FOLLOWING 
IPR  HANDLER.  R0  POINTS 
ITO  THE  TOP  OF  PR 
IHANOLER  ON  RETURN 

1  FROM  THAT  CALL. 

BCS 

FERR 

»N0  PP  HANDLER 

MOV 

R0, FREE 

IUPDATE  FREE  MEMORY 

1  POINTER  TO  POINT  TO 
INEW  BOTTOM  OF  FREE 
f AREA (TOP  OF  HANDLERS), 

.PRINT 

.EXIT 

#0K 

OKI 

.  ASCI Z 
.EVEN 

/FETCH  O.K,/ 

FERRl 

.PRINT 

#MSG 

IPRINT  ERROR  MESSAGE 

.EXIT 

HALT 

1  AND  EXIT 

PRNAMEl 

, WAD50 

"PR  " 

(DEVICE  NAMES 

PPNAMEl 

.RAD50 

«PP  « 

MSG  1 

•  ASCIZ 

"DEVICE  NOT  FOUND"  I  ERROR  MESSAGE 

.EVEN 

FREE! 

.*2 

(POINTER  TO  FREE  MEMORY 

.END 

START 

.GTIM 

9.4.16  .GTIM 


.GTIM  allows  user  programs  to  access  the  current  time  of  day.  The 
time  is  returned  in  two  words,  and  is  given  in  terms  of  clock  ticks 
past  midnight. 


Macro  Call: 
where : 


.GTIM  .area,  .addr 

. addr  is  a  pointer  to  the  two  words  of  time 

to  be  returned. 


Request  Format: 

RO  .area: 


21 


.addr 
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The  high-order  time  is  returned  in  the  first  word,  the  low-order  time 
in  the  second  word.  User  programs  must  make  the  conversion  from  clock 
ticks  to  hours-minutes-seconds .  The  basic  clock  frequency  (50  or  60 
Hz)  may  be  determined  from  the  configuration  word  in  the  monitor  (see 
Section  9.2.6).  The  time  of  day  is  not  reset  at  24:00. 


Errors : 

None. 

Example : 

.MCAll  . ,V2,,.  .REGDEF, ,GTIM,  .EXIT 

..Vi,. 

.REGDEF 


STARTl 

.ffTIM 

•LIST. iTIME 

TIMEl 

.EXIT 

.WORD 

0.0 

I10M  AND  MI  ORDER  TIME 
(RETURNED  MERE. 

UST I 

.BIKW 

2 

(ARGUMENTS  FOR  THE  EMT 

.END 

START 

.GTJB 


9.4.17  .GTJB 

The  .GTJB  request  passes  certain  job  parameters  back  to  the  user 
program. 

Macro  Call:  .GTJB  .area,  .addr 


where:  .addr  is  the  address  of  an  eight-word  block  into 

which  the  parameters  are  passed.  The  values 
returned  are: 


Word  1  -  Job  Number.  0=Background# 

2=Foreground 

2  -  High  memory  limit 

3  -  Low  memory  limit 

4  -  Beginning  of  I/O  channel 

space 

5-8  -  Reserved  for  future  use 


Request  Format: 

R0  4  .area: 


20 


.addr 
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In  the  Single-Job  Monitor,  the  job  number  is  always  0  and  the  low 
limit  0. 

In  the  F/B  Monitor,  the  job  number  can  either  be  0  or  2.  If  the  job 
number  equals  0  (background  job) ,  word  2  equals  0  and  word  4  describes 
where  the  I/O  channel  words  begin.  This  is  normally  an  address  within 
the  Resident  Monitor.  When  a  .CDFN  is  executed,  however,  the  start  of 
the  I/O  channel  area  changes  to  the  user  specified  area . 

Errors : 

None. 


Example  t 


Use  .GTJB  to  determine  if  this  program  is  executing  as  a  foreground  or 
background  job. 


.MCALL  •  •  V2 ( « , . REGDEF , .GTJB, .PRINT, .EXIT 
..V2.. 

.REGDEF 


START! 

.GTJB 

MOV 

T8T 

BNE 

MOV 

111  .PRINT 


iLIBT, iJOBARG  f*0  POINTS  TO  1ST  NORD  ON 
I  RETURN  PROM  CALL. 

#PM8G,R1 

J0BAR6  ! BACKGROUNDS 

IS  f  NO,  PRINT  PM8G 

•BMSC'R} 

R1 


.EXIT 

PMSGI  . ASCIZ  /PROGRAM  IN  FOREGROUND/ 

BM8GI  .ASCIZ  /PROGRAM  IN  BACKGROUND/ 

.EVEN 


LIST*  .BUN  2  |  ARGUMENTS  FOR  THE  EMT 

JOBARGI  .BUM  6,  > JOB  PARAMETERS  PA8SE0  BACK  HERE. 


.END  START 


.HERR/SERR 


9.4.18  .HERR/.SERR 

.HERR  and  .SERR  are  complimentary  requests  used  to  govern  monitor 
behavior  for  serious  error  conditions.  During  program  execution, 
certain  error  conditions  may  arise  which  cause  the  executing  program 
to  be  aborted  (for  example,  trying  to  pass  I/O  to  a  device  which  has 
no  handler  in  memory,  or  trying  to  load  a  device  handler  over  the 
USR) .  Normally,  these  errors  cause  program  termination  with  one  of  the 
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?M-  error  messages.  However,  in  certain  cases  it  is  not  feasible  to 
abort  the  program  because  of  these  errors;  for  example,  a  multi-user 
program  must  be  able  to  retain  control  and  merely  abort  the  user  who 
has  generated  the  error.  .SERR  accomplishes  this  by  inhibiting  the 
monitor  from  aborting  the  job.  Instead,  it  causes  an  error  return  to 
the  offending  EMT  to  be  taken.  On  return  from  that  request,  the  C  bit 
is  set  and  byte  52  contains  a  negative  value  indicating  the  error 
condition  which  occurred. 

.HERR  turns  off  user  error  interception  and  allows  the  system  to  abort 
the  job  on  fatal  errors  and  generate  an  error  message.  (.HERR  is  the 
default  case.) 

Macro  Calls:  .HERR 

.SERR 


Errors : 


Following  is  a  list  of  the  errors  which  are  returned  if  soft  error 
recovery  is  in  effect: 


Code 


Explanation 


-1  Called  USR  from  completion  routine. 

-2  No  device  handler;  this  operation  needs  one. 

-3  Error  doing  directory  I/O. 

-4  FETCH  error.  Either  an  I/O  error 

occurred  while  reading  the  handler,  or  tried  to 
load  it  over  USR  or  RMON. 

-5  Error  reading  an  overlay. 

-6  No  more  room  for  files  in  the  directory. 

-7  Illegal  address  (F/B  only) . 

-10  Illegal  channel  number;  number  is  greater 

them  actual  number  of  channels  which  exist. 

-11  Illegal  EMT;  an  illegal  function  code  has 

been  decoded. 


Traps  to  4  and  10,  and  floating  point  exception  traps  are  not 
inhibited.  These  errors  have  their  own  recovery  mechanism.  (See 
Section  9.4.42.) 


Example : 

This  example  causes  a  normally  fatal  error  to  generate  errors  back  to 
the  user  program.  The  error  returned  is  used  to  print  an  appropriate 
message. 


.NULL 

• .  V2. , , .REGDEF  , 

.FETCH, .ENTER, .HERR, .SERR 

, MC ALL 

•  t  V2, . 
.REGDEF 

.EXIT, .PRINT 

,  SERR 

;turn  on  software  error 
;returns 

.FETCH 

#holr»fptr 

;get  a  device  handler 

BC8 

FCHERR 

.ENTER 

#area,#i,#ptr 

; open  a  file  on  channel  i 

SCI 

ENERR 
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.HERR 

INOW  PERMIT  TM-ERR0R8, 

.EXIT 

FCHERRl 

MOVB 

PPS2.R0 

MAS  IT  FATAL 

SMI 

FTLERR 

f  YES 

.PRINT 

PFM8G 

INO...  NO  DEVICE  BY  THAT  NAME 

.EXIT 

ENERRl 

MOVB 

•»52,R0 

SMI 

FTIERR 

.PRINT 

PEMSG 

.exit 

FTLERRI 

NED 

R0 

ITHIS  WILL  TURN  POSITIVE 

OEC 

R0 

1  ADJUST  BY  ONE 

ASl 

R0 

MAKE  IT  AN  INDEX 

MOV 

TBLCR0),R0 

1  PUT  MESSAGE  ADDRESS  INTO  R0 

.PRINT 

1  AND  PRINT  IT, 

.EXIT 


tbli 

Ml 

I C AN  *  T  OCCUR  IN  THIS  PROGRAM 

M2 

|N0  DEVICE  HANDLER  IN  MEMORY 

Ml 

IDIRECTORY  I/O  ERROR 

M« 

IFETCH  ERROR 

M5 

impossible  FOR  THIS  PROGRAM 

MB 

MO  ROOM  IN  DIRECTORY 

M7 

1  ILLEGAL  AD0RE8S  (F/B) 

Ml  0 

1  ILLEGAL  CHANNEL 

MU 

1  ILLEGAL  EMT 

Mil 

ICAN'T  OCCUR  IN  THIS  PROGRAM 

M2 1 

.  ASCIZ 

/NO  OEVICE  HANDLER/ 

Mil 

•  A8CIZ 

"DIRECTORY  I/O 

ERROR" 

MAI 

.ASCIZ 

/ERROR  DOING  FETCH/ 

M5I 

I  NOT  APPLICABLE  TO  THIS  PROGRAM 

M6I 

.ASCIZ 

/NO  ROOM  IN  OIRECTORY/ 

M7I 

.ASCIZ 

/ADDRESS  CHECK 

ERROR/ 

M10I 

•ASCIZ 

/ILLEGAL  EMT/ 

Mill 

.ASCIZ 

/illegal  DEVICE/ 

FMS6I 

.ASCIZ 

/FETCH  FAILED/ 

EMSGI 

.ASCIZ 

/ENTER  FAILED/ 

.EVEN 

HDLRI 

,BLKW 

300 

1  LEAVE  300  (OCTAL)  FOR  HANDLER 

PTRI 

,  RAD50 

/DTA/ 

IOEV1CE  ANO  FILE  NAME, 

.RAD50 

/exampl/ 

.RAD50 

/MAC/ 

AREA  1 

.BLKW 

« 

1 EMT  AREA 

.END 

ST 

.HRESET 


9.4.19  .HRESET 

This  request  performs  the  same  function  as  .SRESET,  after  stopping  all 
I/O  transfers  in  progress  for  that  job.  (.HRESET  Is  not  used  to  clear 
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/ 


a  hard-error  condition.)  Note  that  in  the  single- job  environment,  a 
hardware  RESET  instruction  is  used  to  terminate  I/O,  while  in  a  F/B 
environment,  only  the  I/O  associated  with  the  job  which  issued  the 
.HRESET  is  affected.  All  other  transfers  continue. 

Macro  call:  .HRESET 

Errors : 

None. 

Example : 

See  the  example  for  .SRESET  (Section  9.4.40)  for  format. 


.LOCK/.UNLOCK 


9.4.20  .LOCK/.UNLOCK 


.LOCK 

The  .LOCK  request  is  used  to  "lock"  the  USR  in  memory  for  a  series  of 
operations.  If  all  the  conditions  which  cause  swapping  are  satisfied, 
the  user  program  is  read  into  scratch  blocks  and  the  USR  is  loaded. 
Otherwise,  the  USR  which  is  in  memory  is  used,  and  no  swapping  occurs. 
The  USR  is  not  released  until  an  .UNLOCK  request  is  given.  (Note  that 
in  a  F/B  System,  calling  the  CSI  may  also  perform  an  implicit 
.UNLOCK.)  A  program  which  has  many  USR  requests  to  make  can  .LOCK  the 
USR  in  memory,  make  all  the  requests,  and  then  .UNLOCK  the  USR;  no 
time  is  spent  doing  unnecessary  swapping. 

In  a  F/B  environment,  a  .LOCK  inhibits  the  other  job  from  using  the 
USR.  Thus,  the  USR  should  be  locked  only  as  long  as  necessary. 

Macro  Call:  .LOCK 

Note  that  the  .LOCK  request  reduces  time  spent  in  file  handling  by 
eliminating  the  swapping  of  the  USR  in  and  out  of  memory.  If  the  USR 
is  currently  resident,  .LOCK  is  ignored.  After  a  .LOCK  has  been 
executed,  an  .UNLOCK  request  must  be  executed  to  release  the  USR  from 
memory.  The  .LOCK/.UNLOCK  requests  are  complimentary  and  must  be 
matched.  That  is,  if  three  .LOCK  requests  are  issued,  at  least  three 
.UNLOCKS  must  be  done,  otherwise  the  USR  will  not  be  released.  More 
.UNLOCKS  than  .LOCKS  may  occur  without  error. 

Notes : 

1.  It  is  vital  that  the  .LOCK  call  not  come  from  within  the  area 
into  which  the  USR  will  be  swapped.  If  this  should  occur, 
the  return  from  the  USR  request  would  not  be  to  the  user 
program,  but  to  the  USR  itself,  since  the  LOCK  function 
inhibits  the  user  program  from  being  re-read. 
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2.  Once  a  .LOCK  has  been  performed,  it  is  not  advisable  for  the 
program  to  destroy  the  area  the  USR  is  in,  even  though  no 
further  use  of  the  USR  is  required.  This  causes 
unpredictable  results  when  an  .UNLOCK  is  done. 

Errors : 

None. 

Example : 

See  the  example  following  .UNLOCK. 


.UNLOCK 

The  .UNLOCK  request  releases  the  User  Service  Routine  from  memory  if 
it  was  placed  there  with  a  .LOCK  request.  If  the  .LOCK  required  a 
swap,  the  .UNLOCK  loads  the  user  program  back  into  memory.  If  the  USR 
does  not  require  swapping,  the  .UNLOCK  acts  as  a  no-op. 

Macro  Call:  .UNLOCK 

Notes : 

1.  It  is  important  that  at  least  as  many  .UNLOCKS  are  given  as 
.LOCKS.  If  more  .LOCK  requests  were  done,  the  USR  remains 
locked  in  memory.  It  is  not  harmful  to  give  more  UNLOCKS 
than  are  required;  those  that  are  extra  are  ignored. 

2.  The  .LOCK/. UNLOCK  pairs  should  be  used  only  when  absolutely 
necessary  when  running  two  jobs  in  the  F/B  system.  When  a 
job  .LOCKS  the  USR,  the  other  job  cannot  get  at  it  until  it 
is  .UNLOCKed.  Thus,  the  USR  should  not  be  .LOCKed 
unnecessarily,  as  this  may  degrade  performance  in  some  cases. 

3.  In  a  F/B  System,  calling  the  CSI  with  input  coming  from  the 
console  terminal  performs  an  implicit  .UNLOCK. 

Errors : 

None. 

Example : 

This  example  shows  the  usage  of  .LOCK,  .UNLOCK,  and  their  interaction 
with  the  system. 

.MCALU  ,.V2.,,  .REGPEP, .LOCK, .UNLOCK, .LOOKUP 
• MC  ALL  .SETTOP, .PRINT, .EXIT 
. a  V2  .  . 

. REGDEF 

START! 

SYSPTR-5A 

.SETTOP  P#8 Y8PTR  » TRY  FOR  ALL  OF  MEMORY 

MOV  R0, TOP  |R0  HAS  THE  TOP 

.LOCK  IBRING  USR  INTO  MEMORY 

.LOOKUP  «LIST,#0,»FIL£1  ILOOKUP  A  PILE  ON  CHANNEL  0 

9-57 


Programmed  Requests 


BCC 

IB 

ION  ERROR,  PRINT  A 

231 

.PRINT 

.EXIT 

«LMBG 

1  MESSAGE  AND  EXIT 

131 

MOV 

•LIST,R0 

INC 

(R0) 

f DO  LOOKUP  ON  CHANNEL 

MOV 

RPILE2, 

2CR0) 

|NE*  POINTER 

.LOOKUP 

I  ALL  ARCS  ARE  PILLED  IN 

BCS 

.UNLOCK 

.EXIT 

23 

1  NON  RELEASE  USR 

LI3TI 

.BLKW 

3 

1  SPACE  FOR  ARGUMENTS 

FILE  l  * 

,  RAD50 

/DK  ✓ 

.RAD50 

/PILII 

MAC/ 

F  X  LE2  3 

.RAD50 

✓  OK  ✓ 

, RAD50 

✓PILE2 

MAC/ 

TOPI 

.WORD 

0 

LM3GI 

. ABC  I Z 
.EVEN 

✓LOOKUP 

ERROR/ 

,EN0 

START 

In  the  above  example,  .SETTOP  tries  to  obtain  as  much  memory  as  It 
can.  Most  likely  this  will.  In  a  background  job,  make  the  USR 
non-resident  (i.e.,  unless  a  SET  USR  NOSWAP  command  Is  done  at  the 
keyboard).  Thus,  If  the  USR  were  non-resident,  swapping  must  take 
place  for  each  .LOOKUP  given.  Using  the  .LOCK,  the  USR  Is  brought 
Into  memory  and  remains  there  until  the  .UNLOCK  Is  given. 

The  second  .LOOKUP  makes  use  of  the  fact  that  the  arguments  have 
already  been  set  up  at  LIST.  Thus,  it  is  possible  to  increment  the 
channel  number,  put  in  a  new  file  pointer  and  then  give  a  simple 
.LOOKUP,  which  does  not  cause  any  arguments  to  be  moved  into  LIST. 


.LOOKUP 


9.4.21  .LOOKUP 

The  .LOOKUP  request  associates  a  specified  channel  with  a  device 
and/or  file,  for  the  purpose  of  performing  I/O  operations.  The 
channel  used  is  then  "busy"  until  one  of  the  following  requests  is 
executed! 


.CLOSE 
.SAVESTATUS 
.S RESET 
.HRESET 
.PURGE 

.CSIGEN  (if  channel  is  in  range  0-10  octal) 
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Macro  Callt  .LOOKUP  .area,  .chan,  .dblk,  .count 

where:  .count  is  an  argument  which  can  optionally  be  used 

for  the  cassette  and  magtape  handlers.  Refer 
to  Appendix  H  for  details  of  this  parameter. 
If  .count  is  blank,  a  value  of  zero  is 
assumed. 


Request  Formats 
RO  4 


.area: 


1 1 . chan 

.dblk 

• count 


If  the  first  word  of  the  file  name  in  .dblk  is  zero  and  the  device  is 
a  file-structured  device,  absolute  block  0  of  the  device  is  designated 
as  the  beginning  of  the  "file”.  This  technique  allows  I/O  to  any 
physical  block  on  the  device.  If  a  file  name  is  specified  for  a 
device  which  is  not  file-structured  (i.e.  PR: FILE. EXT) ,  the  name  is 
ignored. 


The  handler  for  the  selected  device  must  be  in  memory  for  a  .LOOKUP. 
On  return  from  the  .LOOKUP,  RO  contains  the  length  of  the  file  just 
looked  up.  If  the  length  returned  is  0,  either  the  input  device  is 
not  RT-11  file  structured,  or  a  non-file  structured  .LOOKUP  was  done 
to  the  device. 

Errors : 

Code  Explanation 

0  Channel  already  open. 

1  File  indicated  was  not  found  on  the  device. 


Example : 

In  the  following  example,  the  file  "DATA. 001"  on  device  DT3  is  opened 
for  input  on  channel  7. 


• MC ALU  ,,V8.,,,RIGDEF,. FETCH,, LOOK  UP,, PRINT,, EXIT 
..VI., 

.REGDEF 


•TARTl 

ERRWO'SI 

.FITCH 

BCS 

.LOOKUP 

BCC 

TBTB 

BNE 

.PRINT 

.EXIT 

NF0I  .PRINT 
.EXIT 

CAHB6I  ,  ABCIZ 


iHBPACE, PDT3N 
FERR 

•LIST, ST, WIN 

L00NE 

MERRWD 

NFO 

PCAHB6 


f BIT  DEVICE  HANDLER 
(OTJ  18  NOT  AVAILABLE 
(LOOKUP  THE  FILE 
(ON  CHANNEL  T 
(FILE  WAS  FOUND 
(ERROR,  WHAT'S  WR0N8T 
(FILE  NOT  FOUND 
(PRINT  'CHANNEL  ACTIVE* 


PNFM8G  (FILE  NOT  FOUND 

/CHANNEL  ACTIVE/ 
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NFMSGl  .  ASCIZ 
DTM5GI  .ASCIZ 
.EVEN 

FERRl  .PRINT 
.EXIT 

LOONEl 


/FILE  NOT  FOUNO/  ierror  messages 

/DT3  NOT  AVAILABLE/ 


P0TM8G 


IPROGRAM  CAN  NON 
» ISSUE  READS  ANO 
| WRITES  TO  FILE 
IDATA.001  VIA 
(CHANNEL  7 


LISTI 

.EXIT 

.BLKW 

S 

DT3NI 

,  RAD50 

"0T3" 

I0EVICE 

.RAQ30 

"OAT" 

1  FILENAME 

.RAD50 

"A  » 

ifilename 

. RAD50 

"001" 

?  EXTENSION 

HSPACEI 

. • . +400 

.END 

START 

IRESERVED  SPACE  FOR 

ihandler 

.MRKT 


9.4.22  .MRKT 


The  .MRKT  request  schedules  a  completion  routine  to  be  entered  after  a 
specified  time  interval  (clock  ticks  past  midnight)  has  elapsed. 


Macro  Call:  .MRKT  .area,  .time,  .crtn,  .id 


where:  .time  is  the  pointer  to  the  two  words  containing 

the  time  interval  (high-order  first? 
low-order  second) . 


.id  is  a  number  assigned  by  the  user  to  identify 

the  particular  request  to  the  completion 
routine  and  to  any  cancel  mark  time  requests. 
The  number  need  not  be  unique  (i.e.,  several 
.MRKT  requests  may  specify  the  same  .id.)  On 
entry  to  the  completion  routine,  the  .id 
number  is  in  RO. 


Request  Format: 

RO  4 


.area: 
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.MRKT  requests  require  a  queue  element  taken  from  the  same  list  as  the 
I/O  queue  elements.  The  element  is  in  use  until  either  the  completion 
routine  is  entered  or  a  cancel  mark  time  request  is  issued.  The  user 
should  allocate  enough  queue  elements  to  handle  at  least  as  many  mark 
time  requests  as  he  expects  to  have  pending  simultaneously. 

Errors  t 

Code  Explanation 

0  No  queue  element  was  available. 

Example : 


In  this  example,  a  mark  time  is  set  up  to  time  out  an  I/O  transfer. 
If  the  mark  time  expires  before  the  transfer  is  done,  a  message  is 
printed.  If  the  I/O  transfer  completes  before  the  mark  time,  the  mark 
time  is  cancelled.  (Note  that  the  example  assumes  the  I/O  channel  is 
already  open.) 

.MCALL  .  ,V2.., .REGDEF, .REAO, .WAIT, .MRKT, .CMKT 

.MCALL  ,Q  SET, .PRINT, .EXIT, .LOOKUP 

..vs.. 

.REGDEF 


STI 


.LOOKUP 

SCI 

MOV 

.Q3ET 

,MRKT 

BCS 

.READ 

BCS 

.WAIT 

•  CMKT 

BCS 


.EXIT 


•AREA, #0, MILE  (OPEN  A  FILE 
LKERR  I F ILE  NOT  FOUNO 

iAREA,.(SP)  (EMT  LIST  TO  STACK 

ifiUEUE , #5  I  ALLOCATE  5  MORE  ELEMENTS 

(SP),#INTRVL,iMRTN,#l  I  SET  TIMER  GOING 


NOMRKT 
•RDLST 
RDERR 
•  0 

(SP),#J 

NOTDUN 


(FAILED, 
ISTART  I/O 


TRANSFER 


I  AND  WAIT  A  WHILE. 

(  SEE  IF  MARK  TIME  IS 
(DONE , 

(FAILED,  THAT  MEANS  THAT 
(THE  MARK  TIME  ALREADY 
(EXPIRED. 


MRTN* 

LKERR I 

ROERRl 

NOTOUNI 

NOMRKT I 

N00I 

FAIL( 

LMI 

ROMSGI 

INTRVLI 


.CMKT 

.PRINT 

RTS 

.PRINT 

.EXIT 

.PRINT 

.EXIT 

.PRINT 

•  EXIT 

.PRINT 

,CXIT 

.ASCII 

.ASCIZ 

.ASCII 

.ASCII 

.EVEN 

.WORD 


(OK,  KILL  THE  TIMER. 
(DON'T  WORRY  ABOUT  AN 
(ERROR  MERE, 


(8P) , #1 

•  FAIL 

PC 

#lm 

PRDMSG 

•  FAIL 

•  N00 


/NO  QUEUE  ELEMENTS  AVAILABLE/ 

/MARK  TIME  COMPLETED  BEFORE  TRANSFER/ 
/LOOKUP  ERROR/ 

/READ  ERROR/ 


0*19. 


(ALLOW  13  CLOCK 
(TICKS  FOR  TRANSFER, 
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QUEUE  I  ,BLKW  5*7 

AREA  I  iBLKW  5 

FILES  .RAO50  /OK  FILE  T8T/ 

ROLSTI  .BYTE  0 

.BYTE  10 
BLOCKS  .WORD  0 

.WORD  BUFF 
.WORD  256 , 

.WORD  1 

BUFFI  ,BLKW  256, 


SAREA  FOR  QUEUE  ELEMENTS 
|  A  FEW  WORDS  FOR  EMT  LIST 


ICHANNEL  0 


SA  READ 
I  BLOCK  # 

I  buffer 

I I  BLOCK 


•END  ST 


MWAIT 


9.4.23  .MWAIT 

This  request  is  similar  to  the  .WAIT  request.  .MWAIT,  however, 
suspends  execution  until  all  messages  sent  by  the  other  job  have  been 
transmitted  or  received.  It  provides  a  means  for  ensuring  that  a 
required  message  has  been  processed.  It  should  be  used  primarily  in 
conjunction  with  the  .RCVD  or  .SDAT  modes  of  message  handling,  where 
no  action  is  taken  when  a  message  is  completed. 

Macro  Call:  .MWAIT 


Errors 


None 


Example : 


This  program  requests  a  message,  does  some  intermediate  processing, 
and  then  waits  until  the  message  is  actually  sent. 


.MCALL  ,.V2.,,,REGDEF,, MWAIT,, RCVD,, EXIT,. PRINT 

, , V2. , 

.REGOEF 


W0RDS*255 

STARTl 


RCVD  *AREA,«RBUFFi#WORDS  > GET  MESSAGE 


I  INTERMEDIATE  PROCESS 


MOV  #RBUFF*2,R5 

.MWAIT 

CMPB  (R5)*»#'A 

BNE  BAOMSG 


I  MAKE  SURE  WE  HAVE  IT, 
I  FIRST  CHARACTER  AN  A7 
I  NO ,  INVALID  MESSAGE 


.EXIT 

BADMSGI  .PRINT  PMSG 
.EXIT 
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HSGl 

•ASCIZ 

/BAD  MESSAGE/ 

AREA! 

•  SLKW 

10 

RBUFFl 

•  BLKW 

256. 

.EVEN 

•  end 

START 

.PRINT 


9.4.24  .PRINT 

The  .PRINT  request  causes  output  to  be  printed  at  the  console 
terminal.  When  a  change  occurs  in  the  job  producing  output,  a  B>  or 
F>  appears.  Any  text  following  the  message  has  been  printed  by  the 
job  indicated  (foreground  or  background)  until  another  B>  or  F>  is 
printed.  The  string  to  be  printed  may  be  terminated  with  either  a 
null  (0)  byte  or  a  200  byte.  If  the  null  (ASCIZ)  format  is  used,  the 
output  is  automatically  followed  by  a  <CRXLF>.  If  a  200  byte 
terminates  the  string,  no  <CRXLF>  is  generated. 

Macro  Call:  .PRINT  .addr 

where:  .addr  is  the  address  of  the  string  to  be  printed. 

Control  returns  to  the  user  program  after  all  characters  have  been 
placed  in  the  output  buffer. 

The  foreground  job  issues  a  message  immediately  using  .PRINT  no  matter 
what  the  state  of  the  background  job.  Thus,  for  urgent  messages, 
.PRINT  should  be  used  (rather  than  .TTYIN  or  .TTYOUT) . 


Errors : 

None. 

Example: 


.MCAIL  ..V2.., .RE60EF, .PRINT, .EXIT 
.REGDEF 


START! 

.PRINT  #82 
.PRINT  #Si 

.EXIT 


SI!  .ASCIZ  /THIS  Will.  HAVE  CR-LF  FOLLOWING/ 

S2I  .ASCII  /THIS  WILL  NOT  HAVE  CR-LF/ 

.BYTE  200 
•  even 


.END  START 
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.PROTECT 


9.4.25  .PROTECT 

The  .PROTECT  request  is  used  by  a  job  to  obtain  exclusive  control  of  a 
vector  (two  words)  in  the  region  0-476.  If  it  is  successful,  it 
indicates  that  the  locations  are  not  currently  in  use  by  another  job 
or  by  the  monitor,  in  which  case  the  job  may  place  an  interrupt 
address  and  priority  into  the  protected  locations  and  begin  using  the 
associated  device. 

Macro  Call:  .PROTECT  .area,  .addr 

where:  .addr  is  the  address  of  the  word  pair  to  be 

protected.  .addr  must  be  a  multiple  of 
four,  and  must  be  less  them  476  (octal) . 
The  two  words  at  .addr  and  . addr+2  will  be 
protected. 


Request  Format: 

R0  4 


. area : 


31 

0 

.addr 

Errors : 


Code  Explanation 

0  Protect  failure;  locations  already  in  use. 

1  Address  greater  them  476  or  not  a  multiple  of  4. 

Example : 


This  example  shows  the  use  of  .PROTECT  to  gain  control  of  the  UDC11 
vectors . 


. MCALL 

,.vc,. 

.RE60EF 

, ,  V2 ,  • , . RE60EF , . 

PROTECT, .PRINT, .EXIT 

STI 

MOV 

PAREA, •  (8P) 

MOV 

•ISA.RS 

1 UDC  VECTOR  ADDRESS 

.PROTECT  (8P),RS 

IPROTECT  23«,236 

see 

ERR 

1  YOU  CAN'T 

MOV 

•UDCINT, (R5) ♦ 

UNITIALIZE  THE  VECTORS 

MOV 

.EXIT 

#I«0, (RS) 

1  AT  LEVEL  T 

mi 

.PRINT 

.EXIT 

PNOVEC 

ARC  A 1 

,»LKW 

S 

NQVECl 

•ASCII 

/VECTORS  ALREADY 

’  IN  USE/ 
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.EVEN 

UDCINTl 


.PURGE 


9.4.26  .PURGE 

The  .PURGE  request  is  used  to  de-activate  a  channel  without  performing 
a  .HRESET,  .SRESET,  .SAVESTATUS,  or  .CLOSE  request.  It  merely  frees  a 
channel  without  taking  any  other  action.  If  a  tentative  file  has  been 
.ENTERed  on  the  channel,  it  will  be  discarded.  Purging  an  inactive 
channel  acts  as  a  no-op. 

Macro  Calls  .PURGE  .chan 

Errors : 

None. 

Example : 

The  following  code  is  used  to  make  certain  that  channels  0-7  are  free: 

.MCALL  .  ,V2..,  .REGDEF, .PURGE, .EXIT 
. . V2 . . 

.REGOEF 


START! 

CUR 

RI 

ISTART  WITH  CHANNEL  0 

Ill 

.PURGE 

RI 

1  PURGE  A  CHANNEL 

INC 

Rl 

1  BUMP  TO  NEXT  CHANNEL 

CMP 

R 1  *  PS . 

IIS  IT  AT  CHANNEL  S  VET? 

BUO 

IS 

|N0*  KEEP  GOING 

.EXIT 

.end 

START 

.QSET 


9.4.27  .QSET 

All  RT-11  I/O  transfers  are  done  through  a  centralized  queue 
management  system.  If  I/O  traffic  is  very  heavy  and  not  enough  queue 
elements  are  available,  the  program  issuing  the  I/O  requests  may  be 
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suspended  until  ci  queue  element  becomes  available^  In  a  F/B  system, 
the  other  job  runs  while  the  first  program  waits  for  the  element. 

The  .QSET  request  is  used  to  make  the  RT-11  I/O  queue  larger  (i.e., 
add  available  entries  to  the  queue) .  A  general  rule  to  follow  is  that 
each  program  should  contain  one  more  queue  element  than  the  total 
number  of  I/O  requests  which  will  be  active  simultaneously.  Timing 
requests  such  as  .TWAIT  and  .MRKT  also  cause  elements  to  be  used  and 
must  be  included  when  allocating  queue  elements  for  a  program.  Note 
that  if  synchronous  I/O  is  done  (i.e.  . READW/.WRITW,  etc.)  and  no 

timing  requests  are  done,  no  additional  queue  elements  need  be 
allocated. 

Macro  Call:  .QSET  .addr,  .qleng 

where:  .addr  is  the  address  at  which  the  new  elements  are 

to  start. 

.qleng  is  the  number  of  entries  to  be  added.  Each 

queue  entry  is  seven  words  long;  hence  the 
space  set  aside  for  the  queue  should  be 
.qleng  *  7  words. 

Each  time  .QSET  is  called,  a  contiguous  area  of  memory  is  divided  into 
seven-word  segments  and  is  added  to  the  queue  for  that  job.  .QSET  may 
be  called  as  many  times  as  required.  The  queue  set  up  by  multiple 
.QSET  requests  is  a  linked  list.  Thus,  .QSET  need  not  be  called  with 
strictly  contiguous  arguments.  The  space  used  for  the  new  elements  is 
allocated  from  the  user's  program  space.  Thus,  care  must  be  taken  so 
that  the  program  in  no  way  alters  the  elements  once  they  are  set  up. 
The  .SRESET  and  .HRESET  requests  discard  all  user-defined  queue 
elements;  therefore  any  .QSETs  must  be  reissued. 

Care  should  also  be  taken  to  allocate  enough  memory  for  the  queue. 
The  elements  in  the  queue  are  altered  by  the  monitor;  if  enough  space 
is  not  allocated,  destructive  references  will  occur  in  an  unexpected 
area  of  memory. 

Errors : 

None. 

Example : 


i HC ALL 
..V2.. 

, REGDEF 

•  «  V2 . . » 

.REGDE,. QSET, .EXIT 

STAHTI 

.QSET 

#Q1 t *5 

1  ADD  5  ELEMENTS  TO 
) STARTING  AT  Ql 

THE 

QUEUE 

.QSET 

#Q3, #3 

) ANO  3  MORE  AT  Q3. 

.EXIT 

on 

.BIKW 

7*5, 

(FIRST  QUEUE  AREA 

(35 

DECIMAL 

WORDS) 

Q3I 

.BLKW 

7*3, 

(SECONO  QUEUE  AREA 

(21 

DECIMAL 

WORDS) 

.END 

START 

Note  that  Ql  and  Q3  need  not  have  been  contiguous. 
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RCTRLO 


9.4.28  .RCTRLO 

The  .RCTRLO  request  ensures  that  the  console  terminal  is  able  to 
print.  Since  CTRL  O  (to)  struck  while  output  is  directed  to  the 
console  terminal  inhibits  the  output  from  printing  until  either 
another  to  is  struck  or  until  the  program  resets  the  to  switch,  a 
program  that  has  a  message  which  must  appear  at  the  console  cam 
override  to  struck  at  the  keyboard. 

Macro  Call:  .RCTRLO 


Errors : 


None. 


Example : 


In  this  example,  the  user  program  first  calls  the  CSI  in  general  mode, 
then  processes  the  command.  When  finished,  it  returns  to  the  CSI  for 
another  command  line.  To  make  certain  that  the  prompting  typed  by 
the  CSI  is  not  inhibited  by  a  CTRL  0  in  effect  from  the  last 
operation,  terminal  output  is  re-enabled  via  a  .RCTRLO  command  prior 
to  the  CSI  call. 


•  MC ALL  ,.V2.., .REGDEF, .RCTRLO, .CSI6EN,  .EXIT 

. >  V2. . 

.REGDEP 


START!  .RCTRLO 


IRAKI  SURE  TT  OUTPUT  IS 


I  ENABLED 

CSX6EN  PDSPACE, FOEXT , #0  | CALL  C8X-IT  WILL  TYPE 

I"*" 


IPROCESS  COMMAND 


JMP 


START 


I  SET  NEXT  COMMAND 


OIXTI  0 


INO  DEFAULT  EXTENSIONS 


0 

0 

0 


OSPACEI  ,•.*400 


I  HANDLER  SPACE 


.END  START 
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.RCVD/.RCVDC/.RCVDW 


9.4.29  .RCVD/.RCVDC/.RCVDW  (F/B  Only) 

There  are  three  forms  of  the  receive  data  request;  these  are  used  in 
conjunction  with  the  .SDAT  (Send  Data)  requests  to  allow  a  general 
data/message  transfer  system.  .RCVD  requests  can  be  thought  of  as 
.READ  requests,  where  data  transfer  is  not  from  a  peripheral  device 
but  from  the  other  job  in  the  system. 


.RCVD 


This  request  is  used  to  receive  data  and  continue  execution.  The 
request  is  posted  and  the  issuing  job  continues  execution.  At  some 
point  when  the  job  needs  to  have  the  transmitted  message,  an  .MWAIT 
should  be  executed.  This  causes  the  job  to  be  suspended  until  the 
message  has  been  received. 

Macro  Call:  .RCVD  .area,  .buff,  .went 


where:  .buff 

.went 

Request  Format: 


is  the  address  of  the  buffer  to  which 
message  is  to  be  sent. 

is  the  number  of  words  to  be  transferred. 


RO  4 


.area: 


26 


0 


(unused) 

Tb^f* 


.went 

I - 


the 


Word  0  (the  first  word)  of  the  message  buffer  will  contain  the  number 
of  words  transmitted  whenever  the  .RCVD  is  complete.  Thus,  the  space 
allocated  for  the  message  should  always  be  at  least  one  word  larger 
than  the  actual  message  size  expected. 

The  word  count  is  a  variable  number,  and  as  such,  the  .SDAT/. RCVD 
combination  can  be  used  to  transmit  a  few  words  or  entire  buffers. 
The  .RCVD  operation  is  only  complete  when  a  .SDAT  is  issued  from  the 
other  job. 

Programs  using  .RCVD/. SDAT  must  be  carefully  designed  to  either  always 
transmit/receive  data  in  a  fixed  format  or  have  the  capability  of 
handling  variable  formats.  The  messages  are  all  processed  in  FIFO 
(first  in-first  out)  order.  Thus,  the  receiver  must  be  certain  it  is 
receiving  the  message  it  actually  wants . 
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Errors : 

Code  Explanation 

0  No  other  job  exists  in  the  system. 

Example : 

An  example  follows  the  .RCVDW  section. 


•RCVDC 


The  .RCVDC  request  receives  data  and  enters  a  completion  routine  when 
the  message  is  received.  The  .RCVDC  request  is  posted  and  program 
execution  stays  with  the  issuing  job.  When  the  other  job  sends  a 
message,  the  completion  routine  specified  will  be  entered. 


Macro  Call:  .RCVDC  .area,  .buff,  .  went,  .ertn 


where:  .buff 

.went 

.ertn 


is  the  address  of  the  buffer  to  which  the 
message  is  to  be  sent. 

is  the  number  of  words  to  be  transmitted, 
is  the  completion  routine  to  be  entered. 


As  in  the  others,  word  0  of  the  buffer  contains  the  number  of  words 
transmitted  when  the  transfer  is  complete. 

Request  Format: 

RO  4  area: 


26 


(unused) 

.buff 


.went 


.ertn 


Errors : 

Code  Explanation 

0  No  other  job  exists  in  the  system. 


Example : 

An  example  follows  the  .RCVDW  section. 


.RCVDW 

.RCVDW  is  used  to  receive  data  and  wait.  A  message  request  is  posted 
and  the  job  issuing  the  request  is  suspended  until  the  other  job  sends 
a  message  to  the  issuing  job.  When  the  issuing  job  runs  again,  the 
message  has  been  received,  and  word  0  of  the  buffer  indicates  the 
number  of  words  which  were  transmitted. 
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Macro  Call! 
where  s 


. RCVDW  .area,  .buff,  .went 

.buff  Is  the  address  of  the  buffer  to  which  the 

message  is  to  be  sent. 

.went  is  the  number  of  words  to  be  transmitted. 


Request  Format: 


RO  4  .areat 


(unused) 

.buff 


.went 

5 - 


Errors : 


Code 

0 


Explanation 

No  other  job  exists  in  the  system. 


Example : 


In  this  example,  the  running  job  receives  a  message  from  the  second 
job  and  interprets  it  as  the  device  and  filename  of  a  file  to  be 
opened  and  used.  In  this  case,  the  message  was  in  RAD50  format,  and 
the  receiving  program  did  not  use  the  transmitted  length  for  any 
purpose . 


.MCALL 

•RIGOEF 


,.V*,*,.REGOEF,.RC VOW, .PURGE,. LOOKUP,. EXIT,. PRIM 


START! 

MOV  #AREA,RS 
, RCVQW  RS, SPILE, PA 
ecs  MERR 

•PURGE  #0 

•LOOKUP  R5, #0, #F ILE+2 
SCI  LKERR 

.EXIT 

AREA!  ,BLKH  10 

FILE!  ,BLKN  1 

,BLKW  4 


|RS*EMT  ARG,  AREA 
IKEUUEST  MESSAGE  ANU  WAIT 
IAN  ERROR? 

ICLEAR  CHANNEL  0 

ilookup  indicated  file 

f ERROR 


! LEAVE  SPACE  FOR  SAFETY 
FACTUAL  WORD  COUNT  IS  HERE 
!UEV IF ILE ,EXT  ARE  HERE 


MERR! 

•PRINT 
•  EXIT 

SMMIG 

LKERR 1 

•PRINT 

.EXIT 

SLKMSB 

MMSGI 

•ASCII 

/MESSAGE  ERROR/ 

LKMSGI 

•ASCII 
•  EVEN 

/LOOKUP  ERROR/ 

•  ENO 

START 

The  issuing  job  is  suspended  until  the  indicated  data  is  transmitted. 
Either  of  the  other  modes  could  have  also  been  used  to  receive  the 
message. 
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.READ/READC/READW 


9.4.30  . READ/ . RE ADC/. READW 


RT-11  provides  three  modes  of  I/O!  . READ/. WRITE ,  . READC/.WRITC,  and 
• READW/ , WRITW •  Section  9.4.47  explains  the  output  operations.  The 
input  operations  are  described  next. 


.READ 

The  .READ  request  transfers  a  specified  number  of  words  from  the 
specified  channel  to  memory.  Control  returns  to  the  user  program 
immediately  after  the  .READ  is  initiated.  No  special  action  is  taken 
when  the  transfer  is  completed. 


Macro  Call! 

.READ 

.area,  .chan,  .buff,  .went,  .blk 

where  t 

.buff 

is  the  address  of  the  buffer  to  receive 

the 

data  read. 

.went 

is  the  number  of  words  to  be  read. 

.blk 

is  the  block  number  to  be  iread  relative 

to 

the  start  of  the  file,  not  block  0  of  the 
device.  The  monitor  translates  the  block 
supplied  into  an  absolute  device  block 
number.  The  user  program  normally  updates 
•blk  before  it  is  used  again.  If  ,blk«0,  TTt 
gives  t  prompt  and  LPt  gives  form  feed. 
(This  is  true  for  all  .READ  and  .WRITE 
requests . ) 


Request  Format! 


R0  4  .areat 


When  the  user  program  needs  to  access  the  data  read  on  the  specified 
channel,  a  .WAIT  request  should  be  issued.  This  ensures  that  the  data 
has  been  read  completely.  If  an  error  occurred  during  the  transfer, 
the  .WAIT  request  indicates  the  error. 


Notet 

See  note  under  .READW  request 


9-71 


Programmed  Requests 


Errors : 

Code  Explanation 

0  Attempt  to  read  past  end-of-file 

1  Hard  error  occurred  on  channel 

2  Channel  is  not  open 

Example : 

Refer  to  the  . WRITE/. WRITC/.WRITW  examples. 


.RE ADC 


The  .RE ADC  request  transfers  a  specified  number  of  words  from  the 
indicated  channel  to  memory.  Control  returns  to  the  user  program 
immediately  after  the  .RE ADC  is  initiated.  Execution  of  the  user 
program  continues  until  the  .RE ADC  is  complete,  then  control  passes 
to  the  routine  specified  in  the  request.  When  an  RTS  PC  is  executed 
in  the  completion  routine,  control  returns  to  the  user  program. 


Macro  Call: 

.READC 

.area,  .chan,  .buff,  .went,  .ertn 

,  .blk 

where : 

.buff 

is  the  address  of  the  buffer 
data  read. 

to  receive 

the 

.went 

is  the  number  of  words  to  be 

read. 

.ertn 

is  the  address  of  the  user's  completion 

routine . 

.blk 

is  the  block  number  relative 

to  the  start 

of 

the  file,  not  block  0  of  the  device.  The 
monitor  translates  the  block  supplied  into  an 
absolute  device  block  number.  The  user 
program  normally  updates  .blk  before  it  is 
used  again. 


Request  Format: 

RO  4  .area: 


10  . chan 


.blk 


.buff 


.went  

address  of  completion  routine 


When  entering  a  . READC  completion  function  the  following  are  true: 


1.  RO  contains  the  channel  status  word  for  the  operation.  If 
bit  0  of  RO  is  set,  a  hardware  error  occurred  during  the 
transfer.  The  data  may  not  be  reliable. 

2.  Rl  contains  the  octal  channel  number  of  the  operation.  This 
is  useful  when  the  same  completion  function  is  to  be  used  for 
several  different  transfers. 
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Errors : 

Code  Explanation 

0  Attempt  to  read  past  end-of-file 

1  Hard  error  occurred  on  channel 

2  Channel  Is  not  open 

Note: 

See  note  under  .READW  request. 

Example : 

Refer  to  the  .WRITE/. WRITC/.WRITW  examples. 


.READW 


The  .READW  request  transfers  a  specified  number  of  words  from  the 
indicated  channel  to  memory.  Control  returns  to  the  user  program  when 
the  .READW  is  complete  or  if  an  error  is  detected. 


Macro  Call:  .READW  .area,  .chan,  .buff,  .went,  .blk 


where:  .buff  is  the  address  of  the  buffer  to  receive  the 

data  read. 

•went  is  the  number  of  words  to  be  read.  The 

number  must  be  positive. 


.blk  is  the  block  number  relative  to  the  start  of 

the  file,  not  block  0  of  the  device.  The 
monitor  translates  the  block  supplied  into  an 
absolute  device  block  number.  The  user 
program  normally  updates  .blk  before  it  is 
used  again. 


Request  Format: 

RO  4 


.area: 


10  | .chan 

.blk 

.buff 

.went 

3 - 


On  return  from  this  call,  the  C  bit  set  indicates  a  hardware  error  has 
occurred.  If  no  error  occurred,  the  data  is  in  memory  at  the 
specified  address.  In  an  F/B  system,  the  other  job  can  be  run  while 
the  issuing  job  is  waiting  for  the  I/O  to  complete. 


Note: 


Upon  return  from  any  of  the  .READ  EMTs,  RO  contains  the  actual  number 
of  words  read.  This  will  be  less  than  the  requested  word  count  if  an 
attempt  is  made  to  read  past  end-of-file,  but  a  partial  trams fer  is 
possible.  No  error  is  returned  in  this  case.  Therefore,  a  program 
should  always  use  the  returned  word  count  as  the  number  of  words 
available.  For  example,  suppose  a  file  is  5  blocks  long  (i.e.,  it  has 
block  numbers  0  to  4)  and  a  request  is  issued  to  read  512  words. 
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starting  at  block  4.  The  request  is  shortened  to  256  words;  no  error 
is  indicated.  This  does  not  apply  to  non-file  structured  input,  since 
it  is  not  possible  to  know  how  much  data  there  is  to  be  read.  Also 
note  that  since  the  request  will  be  shortened  to  an  exact  number  of 
blocks,  a  request  for  256  words  will  either  succeed  or  fail,  but 
cannot  be  shortened. 


Errors : 

Code  Explanation 

0  Attempt  to  read  past  end-of-file 

1  Hard  error  occurred  on  channel 

2  Channel  is  not  open 

Example  t 

Refer  to  the  .WRITE/.WRITC/.WRITW  examples. 


.RELEAS 


9.4.31  .RELEAS 

The  .RELEAS  request  removes  the  handler  for  the  specified  device  from 
memory.  The  .RELEAS  is  ignored  if  the  handler  is: 

1.  Part  of  RMON  (i.e.,  the  system  device), 

2.  Not  currently  resident,  or 

3.  Resident  because  of  a  .LOAD  command  to  the  Keyboard  Monitor, 

.RELEAS  from  the  foreground  is  always  ignored,  since  the  foreground 
can  only  use  handlers  which  have  been  .LOADed. 

Macro  Call:  .RELEAS  .devname 

where:  .devname  is  the  pointer  to  the  .RAD50  device  name. 


Errors : 

Code 

0 


Explanation 

Handler  name  was  illegal. 
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Example : 

In  the  following  example,  the  DECtape  handler  (DT)  is  loaded  into 
memory,  used,  then  released.  If  the  system  device  is  DECtape,  the 
handler  is  already  resident,  and  .FETCH  will  return  HSPACE  in  RO. 

.HCALI.  .,V2.., ,REG0EF,,FETCH,.RELEA8,,EXJT 

• « V2, « 

(REGDEF 


STARTl  .FETCH  SHSPACE , FQTNAME  ILOAD  OT  HANDLER 


BCS  FERR 

I  USE  HANDLER 

.RELEAS  SDTNAME 

8R  START 

FERRI  HALT 
DTNAMEI  , RAD50  /DT  / 
HSPACE I 


.END  START 


INOT  AVAILABLE 


I  HARK  DT  NO  LONGER  IN 
IMEMORT. 

IDT  NOT  AVAILABLE 
INAME  FOR  DT  HANDLER 
I6EGINNING  OF  HANOLER 
I  AREA 


.RENAME 


9.4.32  .RENAME 

The  .RENAME  request  causes  an  immediate  change  of  name  of  the  file 
specified.  An  error  occurs  if  the  channel  specified  is  not  already 
assigned. 

Macro  Calls  .RENAME  .area,  .chan,  .dblk 


Request  Formats 


RO  4  .areas 


4 

.chan 

.dblk 

The  argument  consists  of  two  consecutive  .RAD50  strings.  For  example s 


DBLKs 


.RENAME 

#AREA,#7,#DBLK 

BCS 

• 

RNMERR 

• 

!rAD50 

/DT3/ 

. RAD50 

/OLDFIL/ 

. RAD50 

/MAC/ 

. RAD50 

/DT3/ 

. RAD50 

/NEWFIL/ 

. RAD50 

/MAC/ 

I USE  CHANNEL  7 
| NOT  FOUND 
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The  first  string  represents  the  file  to  be  renamed  and  the  device  it 
is  found  on.  The  second  represents  the  new  file  name.  If  a  file  with 
the  same  name  as  the  new  file  name  specified  already  exists  on  the 
indicated  device,  it  is  deleted.  The  second  occurrence  of  the  device 
name  DT3  is  necessary  for  proper  operation,  and  should  not  be  omitted. 
The  specified  channel  is  left  inactive  when  the  .RENAME  is  complete. 
.RENAME  requires  that  the  handler  to  be  used  be  resident  at  the  time 
the  .RENAME  request  is  made.  If  it  is  not,  a  monitor  error  occurs. 
Note  that  .RENAME  is  legal  only  on  files  which  are  on  disk  or  DECtape. 
(.RENAMES  to  other  devices  are  ignored.) 


Errors : 

Code  Explanation 

0  Channel  open 

1  File  not  found 

Example  s 

In  the  following  example,  the  file  DATA.TMP  on  DTO  is  renamed  to 
DATA. 001s 


.MCALL  ..V2..,,REGDEF,. FETCH,, PRINT 
, HC ALL  .EXIT, .RENAME 
. « V2« « 

.REGOEF 


#H8PACE,»NAMBLK  IGET  HANDLER 
FERR  fSOME  ERROR 

#AREA,«0,*NAM6LK  IDO  THE  RENAME 
RNMERR  I  ERROR 


8TARTI  .FETCH 
BCI 

.RENAME 

BCI 

.EXIT 

FERRI  .PRINT 
.EXIT 

RNMERR I  .PRINT 
.EXIT 
ARE A I  ,BLKH 

NAMBLKI  .RAO50 
.RAD50 
FM9GI  .ASCII 
RNMSGl  .  ASCIZ 
.EVEN 

HSPACE* . 

.END 


RFMBG 

•RNM8G 

5 

✓DT0OATA  TMP/ 
/DT0OATA  001/ 
/FETCH?/ 
/RENAME?/ 


START 


IR00M  FOR  ARGS. 
I  OLD  NAME 
INEW  NAME 
I  ERROR  MESSAGES 
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.REOPEN 


9.4.33  .REOPEN 

The  .REOPEN  request  reassociates  the  specified  channel  with  a  file  on 
which  a  .SAVESTATUS  was  performed.  The  .SAVESTATUS/. REOPEN 
combination  is  useful  when  a  large  number  of  files  must  be  operated  on 
at  one  time.  As  many  files  as  are  needed  can  be  opened  with  .LOOKUP, 
and  their  status  preserved  with  .SAVESTATUS.  When  data  is  required 
from  a  file,  a  .REOPEN  enables  the  program  to  read  from  the  file.  The 
.REOPEN  need  not  be  done  on  the  same  channel  as  the  original  .LOOKUP 
and  .SAVESTATUS. 


Macro  Call:  .REOPEN  .area,  .chain,  . cblk 


where:  .cblk  is  the  address  of  the  five-word  block  where 

the  channel  status  information  was  stored. 


Request  Format: 


Errors : 

Code 

0 


RO  4  .area: 


6  .chain 


.cblk 


Explanation 

The  specified  channel  is  in  use. 
been  done. 


The  .REOPEN  has  not 


Example : 

Refer  to  the  example  following  the  description  of  .SAVESTATUS. 


9.4.34  . SAVESTATUS 


.  SAVESTATUS 


The  .SAVESTATUS  request  stores  five  data  words  into  a  user-specified 
area  of  memory.  These  words  contain  all  the  information  RT-11 
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requires  to  completely  define  a  file*  When  a  #SAVESTATUS  is  done ,  the 
data  words  are  placed  in  memory,  and  the  specified  channel  is  again 
available  for  use.  When  the  saved  channel  data  is  required,  the 
.REOPEN  request  is  used. 

.SAVESTATUS  can  only  be  used  if  a  file  has  been  opened  with  .LOOKUP. 
If  .ENTER  was  used,  .SAVESTATUS  is  illegal  and  returns  an  error.  Note 
that  .SAVESTATUS  is  legal  only  on  files  which  are  not  on  magtape  or 
cassette. 

Macro  Call:  .SAVESTATUS  .area  .chan,  .cblk 

where:  .cblk  is  the  address  of  the  user  memory  block  (5 

words)  where  the  channel  status  information 
is  to  be  stored. 


Request  Format: 


RO  4  .area: 


5 


chan 


.cblk 


# 


The  five  words  stored  are  the  five  words  normally  contained  in  the 
channel  area,  as  follows: 


Word  #  Contents 

1  Channel  status  word.  The  contents  of  the  bits  of 
this  word  are: 

Bit  #  Contents 

0  1  -  a  hardware  error  occurred  on  this 

channel. 

1-5  Index  into  monitor  tables.  This  describes 

the  physical  device  with  which  the  channel  is 
associated. 

6  1  -  a  .RENAME  operation  is  in  progress  on  the 
channel. 

7  1  -  a  .CLOSE  operation  must  rewrite  the 
directory  (i.e.,  set  when  a  .ENTER  is  done). 

8-12  Contains  the  directory  segment  number 

(1-37(8))  in  which  the  current  open  file  can 
be  found. 

13  1  -  An  end-of-file  was  found  on  the  channel. 

14  Unused. 

15  1  -  This  channel  is  currently  in  use  (i.e.,  a 
file  is  open  on  this  channel) . 

2  Starting  block  number  of  the  file.  Zero  for 
non- file  structured  devices. 


3  Length  of  file  (in  256-word  blocks) . 

4  Data  length  of  file;  currently  unused. 

5  Even  Byte:  I/O  count.  Count  of  how  many  I/O 

requests  have  been  made  on  this  channel.  Odd  Byte: 
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unit  number  of  the  device  associated  with  the  channel 
(between  0  -  7) . 

While  the  .SAVESTATUS/. REOPEN  combination  is  very  useful,  care  must  be 
observed  when  using  it.  In  particular,  the  following  cases  should  be 
avoided : 

1.  If  a  .SAVESTATUS  is  performed  and  the  same  file  is  then 
deleted  before  it  is  reopened,  it  becomes  available  as  an 
empty  space  which  could  be  used  by  the  .ENTER  command.  If 
this  sequence  occurs,  the  contents  of  the  file  supposedly 
saved  will  change. 

2.  Although  the  device  handler  for  the  required  peripheral  need 
not  be  in  memory  for  execution  of  a  .REOPEN,  if  the  handler 
is  not  in  memory  when  a  .READ  or  .WRITE  is  executed,  a  fatal 
error  is  generated. 

Errors : 

Code  Explanation 

0  The  channel  specified  is  not  currently  associated 

with  any  file,  i.e.  a  previous  .LOOKUP  on  the 
channel  was  never  done. 

1  The  file  was  opened  via  .ENTER,  or  is  a  magtape  or 

cassette  file,  and  a  .SAVESTATUS  is  illegal. 

Example : 

One  of  the  more  common  uses  of  .SAVESTATUS  and  .REOPEN  is  to 
consolidate  all  directory  access  motion  and  code  at  one  place  in  the 
program.  All  files  necessary  are  opened  and  their  status  saved,  then 
they  are  re— opened  one  at  a  time  as  needed.  USR  swapping  can  be 
minimized  by  locking  in  the  USR,  doing  .LOOKUPS  as  needed,  using 
.SAVESTATUS  to  save  the  file  data,  and  then  .UNLOCKing  the  USR. 

In  the  program  segment  below,  three  input  files  are  specified  in  the 
command  string;  these  are  then  processed  one  at  a  time. 


.MCALL 

..V2,., .REGOEF 

, .CSIGEN,. SAVESTATUS, .REOPEN 

.MCALL 

.READ, .EXIT 

. .  V2, . 

.  REGOEF 

% 

START!  MOV 

PARE  A , R5 

.CSIGEN 

PDSPACE , #DE  XT 

(GET  INPUT  FILES 

MOV 

R0, BUFF 

(SAVE  POINTER  TO  FREE  CORE 

.SAVESTATUS  R5» #1, fBLOCK 1  (SAVE  FIRST  INPUT  FILE 
.SAVESTATUS  R5, *«, PBL0CK2  ;SAVE  SECOND  FILE 
.SAVESTATUS  R5, #5, #BL0CK3  f SAVE  THIRD  FILE 


MOV  #BL0CK1,R« 

PROCESS!  .REOPEN  R5,#0,R«  fREOPEN  FILE  ON 

(CHANNEL  0 

•READ  R5,#0, BUFF, COUNT, BLOCK  (PROCESS  FILE  ON  CHANNEL  0 

OONEI  ADO  #12, RA  (POINT  TO  NEXT  SAVESTATUS  BLOCK 

CHP  R«,#BL0CK3  (LAST  FILE  PROCESSED! 
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BLOB 

.EXIT 

PROCESS 

f NO  •  00  NEXT 

BL0CK1I 

.WORD 

0f0f0f0r0 

IMEMORV  BLOCKS  FOR 

BL0CK2I 

.WORD 

0  r  0  r  0  i  0  *  0 

ISAVESTATUS  INFORMATION 

BLOCKS! 

.WORD 

0i  0f  0f  0r  0 

AREA  I 

,BLKW 

10 

BUFFI 

.WORD 

0 

BLOCK! 

,W0R0 

0 

COUNT! 

.WORD 

lit. 

DEXTl 

OSPACE* 

.WORD 

’.END 

0f  0  9  Zf  0 

8TANT 

.  S  DAT / S DAT C/ SDAT W 


9.4.35  .SDAT/.SDATC/.SDATW 

These  requests  are  used  in  conjunction  with  the  .RDVD/.RCVDW/.RCVDC 
calls  to  allow  message  transfers  with  RT-11.  .SDAT  transfers  can  be 
considered  similar  to  .WRITE  requests  in  which  data  trans fer  is  not 
from  a  peripheral,  but  from  one  job  to  another. 


.SDAT 

Macro  Call:  .SDAT  .area,  .buff,  .went 

where:  .buff  is  the  buffer  address  of  the  beginning  of  the 

message  to  be  trans f erred. 

.went  is  the  number  of  words  to  transfer. 

Request  Format: 

RO  $  .area: 


Explanation 
No  other  job  exists. 


Errors : 
Code 
0 


25  0 


unused 


.buff 


.went 
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Example : 

See  the  example  following  . SDATW. 


•SDATC 

Macro  Call:  .SDATC  .area,  .buff,  .went,  .ertn 


where:  .buff 

.went 

.ertn 


Is  the  buffer  address  of  the  beginning  of  the 
message  to  be  transferred. 

is  the  number  of  words  to  transfer. 

is  the  address  of  the  completion  routine  to 
be  entered  when  the  message  has  been 
transmitted. 


Request  Format: 


RO  4  .area: 


25 


unused 


.buff 


.went 


.ertn 


Errors : 
Code 


Explanation 
No  other  job  exists. 


Example : 

See  the  example  following  .SDATW. 

.SDATW 

Macro  Call  .SDATW  .area,  .buff,  .went 


where:  .buff 

.went 

Request  Format: 

RO  4  .area: 


is  the  buffer  address  of  the  beginning  of  the 
message  to  be  transferred 

is  the  number  of  words  to  transfer 


25 


unused 


.buff 

.went 
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Errors  t 

Code  Explanation 

0  No  other  job  exists. 

Example : 

In  this  example ,  the  job  first  sends  a  message  interrogating  the  other 
job  about  the  status  of  an  operation,  and  then  looks  for  an 
acknowledgement  from  the  job. 


•  MC  ALL  ..V2,,* .REGOEF, .3DAT, .RCVD, .MWAIT, .PRINT* .EXIT 
» • V2 . » 

.RE60EF 

STARTl 


MOV 

RAREA.R5 

1  SET  UP  EMT  BLOCK 

.BOAT 

R5#  FSBUFF . FMLGTM 

1  | ASK  HIM  A  QUESTION 

BCS 

NOJOB 

1  NO  OTHER  JOB  AROUND t 

f MISCELLANEOUS  PROCESSING 

.RCVO 

R5,#BUFF2,#20, 

f RECEIVE  20  DECIMAL  WOROS 

.MWAIT 

>  WAIT  FOR  ACKNOWLEDGE. 

MOV 

#BUFF2*2*  R1 

f POINT  TO  ACTUAL  ANSWER, 

CMPB 

(Rn**#»v 

*18  FIRST  WORO  Y  FOR  TEST 

BNE 

PRNE6 

| NEGATIVE  ACKNOWLEDGE 

.PRINT 

FP08ACK 

.EXIT 

\ 

PRNEGl 

.PRINT 

.EXIT 

FNEGACK 

(NEGATIVE  ON  OUR  INQUIRY 

SBUFFl 

.ASCII 

/IS  THE  REQUIRED 

PRQCES8  GOING?/ 

MLGTH», 

•SBUFF 

BUFF2 1 

.  WORD 

0 

(ACTUAL  LENGTH  IS  HERE 

.BLKN 

20. 

(SPACE  FOR  20.  WORDS 

NOJOB  1 

.PRINT 

.EXIT 

#N JMSG 

NEGACKI 

.asciz 

/NEGATIVE  ACKNOWLEDGE/ 

POSACM 

.ASCIZ 

/POSITIVE  ACKNOWLEDGE/ 

NJMSGl 

.ASCIZ 

.EVEN 

/NO  JOB/ 

AREA  1 

.BLKN 

IB. 

.End 

START 

.SETTOP 


9.4.36  .SETTOP 


The  .SETTOP  request  allows  the  user  program  to 
address  be  specified  as  a  program's  upper 


request  that  a  new 
limit.  The  monitor 
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determines  whether  this  address  is  legal  and  whether  or  not  a  memory 
swap  is  necessary  when  the  USR  is  required.  For  instance ,  if  the 
program  specified  an  upper  limit  below  the  start  address  of  USR,  no 
swapping  is  necessary,  as  the  USR  is  not  overlaid.  If  .SETTOP  from 
the  background  specifies  a  high  limit  greater  than  the  address  of  the 
USR  and  a  SET  USR  NOSWAP  command  has  not  been  given,  a  memory  swap  is 
not  required.  Section  9.2.5  gives  details  on  determining  where  the 
USR  is  in  memory  and  how  to  optimize  the  .SETTOP. 

On  return  from  .SETTOP,  both  RO  and  the  word  at  location  50  (octal) 
contain  the  highest  memory  address  allocated  for  use.  If  the  job 
requested  an  address  higher  than  the  highest  address  which  is  legal 
for  the  requesting  job,  it  is  adjusted  down  to  that  address. 

Macro  Call:  .SETTOP  .addr 

where:  .addr  is  the  address  of  the  word  immediately 

following  the  free  area  desired. 

Notes : 

1.  A  program  should  never  do  a  .SETTOP  and  assume  that  its  new 
upper  limit  is  the  address  it  requested.  It  must  always 
examine  the  returned  contents  of  RO  or  location  50  to 
determine  its  actual  high  address. 

2.  In  Version  1  of  RT-11,  RO  did  not  return  the  high  address  in 
RO,  but  only  in  word  50. 

3.  It  is  imperative  that  the  value  returned  in  RO  or  location  50 
be  used  as  the  absolute  upper  limit.  If  this  value  is  ever 
exceeded,  vital  parts  of  the  monitor  may  be  destroyed,  and 
the  system  integrity  will  be  violated. 

Errors : 

None. 

Example : 

Following  is  an  example  in  two  parts.  The  first  indicates  how  a 
background  job  can  be  assured  of  reserving  space  up  to  but  not 
including  the  USR.  This  in  effect  gives  the  job  all  the  space  it  can 
without  causing  the  USR  to  become  non-resident. 

The  second  part  indicates  how  to  always  reserve  the  maximum  amount  of 
space  by  making  the  USR  non-resident. 

I)  .NCM.I  ,.V2..,.REGDEF, .SETTOP, .EXIT 

a • V2  ,  , 

a REGDEF 


START  I 
RM0M5A 
USRf 266 
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MOV 

•PRMON , R 1 

ISTART  OP  RMON  TO  Ri 

.SETTOP 

USR (R 1 ) 

1266  BYTES  INTO  RESIDENT  IS  A  WORD 
1  WHICH  ALWAYS  INDICATES  WHERE  THE 

1 USR  BEGINS, 

MOV 

R0#  HICORI 

IR0  CONTAINS  THE  HIGH  ADDRESS 

ITHAT  WAS  RETURNED. 

•SETTOP 

#-2 

1  IF  WE  ASK  FOR  A  VALUE  GREATER 
ITHAN  START  OF  RESIDENT#  WE 
f  MILL  GET  BACK  THE  ABSOLUTELY 

I  HIGHEST  USABLE  ADDRESS. 

MOV 

R0»  HICORE 

ITHAT  IS  OUR  LIMIT  NOW 

•  EXIT 

HICOREI  .MONO 

0 

•  END 

START 

If  a  SET  USR  NOSWAP  command  is  executed ,  the  USR  cannot  be  made 
non-resident.  In  this  case,  in  both  I  &  II  above,  RO  would  return  a 
value  just  below  the  USR. 


.SFPA 


9.4.37  .SFPA 


.SFPA  allows  users  with  floating  point  hardware  (FPP  on  11/45  and  FIS 
on  11/40)  to  set  trap  addresses  to  be  entered  when  a  floating  point 
exception  occurs.  If  no  user  trap  address  is  specified  and  a  floating 
point  (FP)  exception  occurs,  a  7M-FP  TRAP  occurs,  and  the  job  is 
aborted. 


Macro  Call: 
where : 


.SFPA  .area,  .addr 

. addr  is  the  address  of  the  routine  to  be 

when  an  exception  occurs. 


Request  Format: 

RO  $  .area: 


30  0 


.addr 


Notes : 


entered 


1.  If  the  address  argument  is  0,  user  floating  point  routines 
are  disabled  and  the  fatal  7M-FP  TRAP  error  is  produced. 

2.  In  the  F/B  environment,  an  address  value  of  1  indicates  that 
the  FP  registers  should  be  switched  when  a  context  switch 
occurs,  but  no  user  traps  are  enabled.  This  allows  both  jobs 
to  use  the  FP  unit.  An  address  of  1  to  the  Single-Job 
Monitor  is  equivalent  to  an  address  of  0. 
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3.  When  the  user  routine  is  activated,  it  is  necessary  to 

re-execute  an  .SFPA  request,  as  the  monitor  inhibits  user 
traps  when  any  one  is  serviced.  It  does  this  to  inhibit  any 
possible  infinite  loop  being  set  up  by  repeated  FP 

exceptions . 

4.  If  the  11/45  FPP  is  being  used,  the  instruction  STST  -(SP)  is 

executed  by  the  monitor  before  entering  the  user's  trap 
routine.  Thus,  the  trap  routine  must  pop  the  two  status 
words  off  the  stack  before  doing  an  RTI.  The  program  can 
tell  if  FPP  hardware  is  available  by  examining  the 

configuration  word  in  the  monitor  (see  Section  9.2.6). 

Errors : 

None. 

Example : 

This  example  sets  up  a  user  FP  trap  address. 


.MCAUl  ,  .V2.., .REGDEF, .SFPA, .EXIT 

M^2«| 

.REGDEF 

8 TARTl 

,3FPA  FARE A i FFPTRAP 

.EXIT 

FPTRAPl 


, SFPA  FARE A , FFPTRAP 
RTI 

AREA  I  .BLKW  10 

.END  START 


9.4.38  .SPFUN 


.SPFUN 


This  request  is  used  only  in  conjunction  with  cassette  and  magtape 
handlers.  It  provides  a  means  for  doing  device-dependent  functions, 
such  as  rewind  and  backspace,  to  those  devices.  If  .SPFUN  is 
requested  for  any  device  except  MT  and  CT,  the  request  is  ignored. 


Macro  Calls  .SPFUN 
where :  • code 


.area,  .chan,  .code,  .buff,  .went,  .ertn,  .blk 

is  the  numerical  code  of  the  function  to  be 
performed 
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.crtn  is  the  entry  point  of  a  completion  routine. 

If  left  blank,  0  is  automatically  inserted. 

Request  Formats 


RO  $  .areas 


All  other  arguments  are  the  same  as  those  defined  for  .READ/. WRITE 
requests  (Sections  9.4.30  and  9.4.47).  They  are  only  required  when 
doing  a  .WRITE  with  extended  record  gap  to  MT.  If  the  .crtn  argument 
is  left  blank,  the  requested  operation  will  complete  before  control 
returns  to  the  user  program.  . crtn=l  is  equivalent  to  executing  a 
.READ  or  .WRITE  in  that  the  function  is  initiated  and  returns 
immediately  to  the  user  program.  A  .WAIT  on  the  channel  ensures  that 
the  operation  is  completed.  If  . crtn=N ,  it  is  taken  as  a  completion 
routine  address  to  be  entered  when  the  operation  is  complete. 

The  available  functions  and  their  codes  ares 


Function 

MT 

CT 

Forward  to  last  file 

377 

Forward  to  last  block 

376 

Forward  to  next  file 

375 

Forward  to  next  block 

374 

Rewind  to  load  point 

373 

373 

Write  file  gap 

372 

Write  EOF 

377 

Forward  1  record 

376 

Backspace  1  record 

Write  with  extended 

375 

file  gap 

374 

Offline 

372 

To  use  the  .SPFUN  request,  the  handler  must  be  in  memory  and  a  channel 
associated  with  a  file  via  a  .LOOKUP  request. 

Refer  to  Appendix  H  for  details  of  MT  and  CT  handlers. 

Errors  t 

Errors  are  detected  in  the  same  way  as  for  the  . READ/ . READC/ • READW 
requests.  Refer  to  Section  9.4.30  for  details. 

Example: 

The  following  example  rewinds  a  cassette  and  writes  out  a  256-word 
buffer  and  then  a  file  gap. 

.MCALL  ,.V2.., .REGOEF, .FETCH, . LOOKUP , , SPFUN, , WR I TW 
, MC ALL  .EXIT, .PRINT, .WAIT, .CLOSE 
. .  V  2  .  . 

, RECOEF 

STARTl 

.FETCH  «HSPC,*CT  »CET  A  HANDLER 
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BCS 

FERR 

IFETCH  ERROR 

.LOOKUP 

PAREA, P4, PCT 

fLOOK  IT  UP  ON  CHANNEL  4 

BCS 

LKERR 

HOOKUP  ERROR 

. SPFUN 

•  AREA#  #4, PITS 

IREWIND  SYNCHRONOUSLY 

BCS 

SPERR 

IAN  ERROR  OCCURREO. 

MOV 

P3*  R5 

ICOUNT 

1  BLOCK  0. 

.VRITW 

PAREA# P4, PBUFF  # 

P2S6..BLK 

BCS 

WTERR 

.SPFUN 

PAREA, P4, *372, , 

,Pi  1  ASYNCHRONOUS  FILE  GAP 

.PRINT 

PDONE 

.WAIT 

P4 

1  WAIT  FOR  DONE 

.CLOSE 

.EXIT 

P4 

1  CLOSE  THE  FILE 

AREA  1 

,  BLKW 

10 

F0RRI 

.PRINT 

.EXIT 

PFHSG 

LKERRt 

.PRINT 

.EXIT 

PLKMS6 

SPERRl 

.PRINT 

.EXIT 

PSPMSG 

WTERRt 

.PRINT 

.EXIT 

PWTMSG 

DONEI 

.  A8CIZ 

/ALL  DONE/ 

FMSGI 

.ASCII 

/FETCH!/ 

LKMSGt 

.ASCII 

/FILE?/ 

SPMSGl 

•  A  SCI z 

/SPECIAL  FUNCTION  ERROR/ 

WTMSGI 

.ASCII 

.EVEN 

/WRITE  ERROR/ 

CTl 

.RAO50 

/CT  / 

.WORD 

0,0,0 

BUFFI 

.BLKW 

ass. 

BI.KI 

HSPC*. 

.WORD 

0 

.END 

START 

.SPND/.RSUM 


9.4.39  .SPND/.RSUM  (F/B  only) 

The  .SPND/ .RSUM  requests  allow  a  job  to  control  execution  of  its 
mainstream  code  (that  code  which  is  not  executing  as  a  result  of  a 
completion  routine) .  .SPND  suspends  the  mainstream  and  allows  only 
completion  routines  (for  I/O  and  mark  time  requests)  to  run.  .RSUM 
from  one  of  the  completion  routines  resumes  the  mainstream  code. 
These  functions  enable  a  program  to  wait  for  a  particular  I/O  or  mark 
time  request  by  suspending  the  mainstream  and  having  the  selected 
event's  completion  routine  issue  a  .RSUM.  This  differs  from  the  .WAIT 
request,  which  suspends  the  mainstream  until  all  I/O  operations  on  a 
specific  channel  have  completed. 
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.SPND 


Macro  Call:  .SPND 
where:  RO 


.  RSUM 


Macro  Call:  .RSUM 
where :  RO  # 


Notes : 


1.  The  monitor  maintains  a  suspension  counter  for  each  job. 
This  counter  is  decremented  by  .SPND  and  incremented  by 
.RSUM.  A  job  will  actually  be  suspended  only  if  this  counter 
is  negative.  Thus,  if  a  .RSUM  is  issued  before  a  .SPND,  the 
latter  request  will  return  immediately. 

2.  A  program  must  issue  an  equal  number  of  .SPNDs  and  .RSUMs. 

3.  A  .RSUM  request  from  the  mainstream  code  increments  the 
suspension  counter. 

4.  A  .SPND  request  from  a  completion  routine  decrements  the 
suspension  counter,  but  does  not  suspend  the  mainstream.  If 
a  completion  routine  does  a  .SPND,  the  mains tream  continues 
until  it  also  issues  a  .SPND,  at  which  time  it  is  suspended 
and  will  require  two  .RSUMs  to  proceed. 

5.  Since  a  .TWAIT  is  simulated  in  the  monitor  using  suspend  and 
resume,  a  .RSUM  issued  from  a  completion  routine  may  cause 
the  mains tream  to  continue  past  a  timed  wait  before  the 
entire  time  interval  has  elapsed. 

Errors : 

None. 

Example : 

In  this  example,  the  program  starts  a  number  of  read  operations  and 

suspends  itself  until  at  least  two  of  them  are  complete. 


.MCALL  .  ,V2,., .RE6DEF, .SPND, .RSUM, , RE ADC, .EXIT, .LOOKUP 
,  MCAIL  .PRINT, .WAIT 
i  •  V2 . . 

.REGDEF 

START! 

.LOOKUP  VAREA, #2, FFILE2 
BCS  IS 

.LOOKUP  FARE A , *3, #F I LE3 
BCS  IS 

.LOOKUP  »AREA,«4,»FILE4 
BCC  38 
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191 

.PRINT 

.EXIT 

•  29 

291 

.  ASCIZ 
.EVEN 

/LOOKUP  ERROR/ 

391 

MOV 

•2.R8VCTR  MAIT  FOR  2  COMPLETIONS 

MOV 

f AREA ,  R5 

.REAOC 

R5,#2,#BUF1, COUNT l,ACROUTN, BLOK  1 

BOB 

ERROR 

.REAOC 

R5,#3,#BUF2,C0UNT2,»CR0UTN,BL0K2 

BC9 

ERROR 

.REAOC 

R5,i4,#BUF3, COUNTS. «CROUTN, BLOKS 

BC9 

.  8PN0 

ERROR 

.WAIT 

•  2 

.WAIT 

•  S 

.WAIT 

.EXIT 

«« 

CROUTNI 

AIL 

Rl  1  DOUBLE  CHANNEL  •  FOR  INOEXINfi 

INC 

DONEFL(Rl)  | RJ ^CHANNEL  THAT  19  DONE 

1  SET  A  FLAG  SAVING  90, 

ROR 

R0  I  ANY  ERRORS? 

ADC 

ERRFLGCRi)  I  IF  CARRY  SET,  SET  ERROR  FLAG  FOR  CHANNEL 

DEC 

R9VCTR  t ARE  WE  THE  SECOND  TO  FINISH? 

BNE 

19  1  NO 

.R9UM 

1  YES,  START  UP 

191 

RT9 

PC 

CRRQRl 

.PRINT 

.EXIT 

•ROMSG 

ROMSGl 

.A9CIZ 

.EVEN 

/READ  ERROR/ 

AREA  1 

.BLKW 

10 

RSVCTRI 

.WORD 

0 

COUNT  1 1 

.WORD 

256, 

C0UNT2I 

.WORD 

256, 

C0UNT3 1 

.MONO 

256, 

BLOK  1 1 

.WORD 

0 

BuOK2l 

.wOKO 

0 

BL0K3I 

.WORD 

0 

FILE2I 

,  RAO50 

/DK  TEST2  TMP/ 

FILESl 

.RAO50 

/OK  TESTS  TMP/ 

FILE*  1 

.RAO50 

/OK  TESTA  TMP/ 

DONEFLI 

.WORD 

0,0,0 

ERRPLGl 

.WORD 

0,0,0 

BUF 1  • 

.BLKW 

256. 

BuFSI 

.BLKM 

256, 

BUF3 1 

.BLKW 

256. 

.END 

START 
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.SRESET 


9.4.40  .SRESET 

The  .SRESET  (software  reset)  request  performs  the  following  functions: 

1.  Dismisses  any  device  handlers  which  were  brought  into  memory 
via  a  .FETCH  call.  Handlers  which  were  loaded  via  the 
Keyboard  Monitor  LOAD  command  remain  resident,  as  does  the 
system  device  handler. 

2.  Purges  any  currently  open  files.  Files  opened  for  output 
with  .ENTER  will  never  be  made  permanent. 

3.  Reverts  to  using  only  16  (decimal)  I/O  channels.  Any 
channels  defined  with  .CDFN  are  disregarded.  A  .CDFN  must  be 
reissued  to  open  more  than  16  (decimal  channels  after  a 
.SRESET  is  performed. 

4.  Resets  the  I/O  queue  to  one  element. 

5.  Initializes  locations  40-57. 

Macro  Call  .SRESET 


Errors : 
None. 
Example : 


In  the  example  below,  .SRESET  is  used  prior  to  calling  the  CSI  to 
ensure  that  all  handlers  are  removed  from  memory  and  the  CSI  is 
started  with  a  free  handler  area. 

.MCALL  .REGDEF, .CSIGEN, .SRESET# .EXIT 

. <  V2 1  . 

.REGDEF 


START  I  , CSIGEN  AOSPACE, AQEXT, #0  I  GET  COMMAND  STRING 

MOV  R0, BUFFER  |R0  POINTS  TO  FREE  MEMORY 


00NEI  .SRESET 

8R  START 


I  RELEASE  HANDLERS,  DELETE 
I  TENTATIVE  FILES 
I  AND  REPEAT  PROGRAM, 
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DEXT I  .WORD  0,0, 0,0 

BUFFER!  0 
OSPACEt , 


JSTART  OF  HANDLER  AREA, 


INO  DEFAULT  EXTENSIONS 


.END  START 


If  the  .SRESET  had  not  been  performed  prior  to  the  second  call  of 
. CSIGEN ,  it  is  possible  that  the  second  command  string  would  load  a 
handler  over  one  that  the  monitor  thought  was  resident  from  the  first 
command  line. 


TLOCK 


9.4.41  .TLOCK 

.TLOCK  is  used  in  an  F/B  system  to  attempt  to  gain  ownership  of  the 
USR.  It  is  similar  to  .LOCK  in  that  if  successful,  the  user  job 
returns  with  the  USR  in  memory.  However,  if  a  job  attempts  to  .LOCK 
the  USR  while  the  other  job  is  using  it,  the  requesting  job  is 
suspended  until  the  USR  is  free.  With  .TLOCK,  if  the  USR  is  not 
available,  control  returns  immediately  with  the  C  bit  set  to  indicate 
the  .LOCK  request  failed. 

Macro  Call:  .TLOCK 

The  .TLOCK  request  allows  the  job  to  continue  running,  with  only  one 
sub- job  affected.  With  a  .LOCK  request,  all  sub- jobs  would  be 
automatically  suspended,  and  the  other  job  in  the  system  would  run. 

Request  Format: 


RO :  $  area:  70 


Errors : 


Code 


Explanation 

USR  is  already  in  use  by  another  job. 


0 


Example : 


In  the  following  example,  the  user  program  needs  the  USR  for  a  sub- job 
it  is  executing.  If  it  fails  to  get  the  USR  it  suspends  that  sub-job 
and  runs  another  sub- job.  This  type  of  procedure  is  useful  to 
schedule  several  sub-jobs  within  a  background  or  foreground  program. 


.MCALL  ,.V2,,, .RE6DEF, .TLOCK, .LOOKUP, .UNLOCK, .EXIT, .PRINT 


START! 
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. TLOCK 

BCS  8U8PND 

.LOOKUP  #AREA,#«,#J1 
BCS  LKERR 

.UNLOCK 


.EXIT 

SU3PNDI  JSR  PC . SP8J0B 

J8R  PC.8CHED 


/  GET  THE  U8R 

/FAILED,  SUSPEND  SUB-JOB 
NAM  /LOOKUP  A  FILE 

/RELEASE  USR 


/SUSPEND  SUB-JOB 

/AND  SCHEDULE  NEXT  USER 


AREA!  ,BLKW 
J 1  NAM  I  .RAD50 
LKERRl  .PRINT 
.EXIT 

LKMS&I  .  A  SC  I Z 

.even 

SPSJOBI  RTS 
SCHEOl  RTS 


10 

/OK  TEST!  TMP/ 
PLKMSG 

/LOOKUP  ERROR/ 

PC 

PC 


.END  START 


.TRPSET 


9.4.42  .TRPSET 

.TRPSET  allows  the  user  job  to  intercept  traps  to  4  and  10  instead  of 
having  the  job  aborted  with  a  7M-TRAP  TO  4  or  7M-TRAP  TO  10  message. 
If  .TRPSET  is  in  effect  when  a  trap  occurs,  the  user-specified  routine 
is  entered.  The  sense  of  the  C  bit  on  entry  to  the  routine  determines 
which  trap  occurred:  C  bit  clear  indicates  a  trap  to  4?  set  indicates 
a  trap  to  10.  The  user  routine  should  exit  via  an  RTI  instruction. 


Macro  Call:  .TRPSET  .area,  .addr 

where:  .addr  is  the  address  of  the  user's  trap  routine. 

If  an  address  of  0  is  specified,  the  user's 
trap  interception  is  disabled. 


Request  Format: 

R0  $  .area: 


3  0 


.addr 


Notes : 

It  is  necessary  to  reissue  a  .TRPSET  request  whenever  a  trap  occurs 
and  the  user  routine  is  entered.  The  monitor  inhibits  servicing  user 
traps  prior  to  entering  the  first  user  trap  routine.  Thus,  if  a  trap 
should  occur  from  within  the  user's  trap  routine,  a  7M-TRAP  message  is 
generated.  The  last  operation  the  user  routine  should  perform  before 
an  RTI  is  to  reissue  the  .TRPSET  request. 
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Errors  t 
None. 
Example : 


The  following  example  sets  up  a  user  trap  routine  and,  when  the  trap 
occurs,  prints  an  appropriate  error  message. 

.MCAU.  ,,V2,.,.R£GDEP,. TRPSET,,  EXIT,,  PRINT 
, ,  V  2 , , 

.REGDEP 


STARTl 


.TRPSET 
MOV 
TIT 
.WORD 
•  EXIT 


TRRLOCI  BCS 

.PRINT 

BR 

HI  .PRINT 

211  .TRPSET 

RTI 


AREA  I  .BIKW 
TRP4I  ,  ASCIZ 
TRP10I  .ASCIZ 
.EVEN 


•AREA , PTRPLOC 
•101. RB 
(R0)  * 

IT 


II 

•  TRP4 
21 

•TRPie 

•AREA, PTRPLOC 


10 

/TRAP  T0  4/ 
/TRAP  TB  10/ 


.END  START 


I  SET  TO  PRODUCE  A  TRAP 
I  THIS  WILL  TRAP  TO  4, 
ITHIS  WILL  TRAP  TO  10, 


1C  SET  »  TRAP  TO  10, 
I  TRAP  TO  4 

ITRAP  TO  10 
IRESET  TRAP  ADDRESS 


XTYIN/.TTINR 


9.4.43  . TTYIN/TTINR 

These  requests  are  used  to  transfer  characters  from  the  console 
terminal  to  the  user  program.  The  character  thus  obtained  appears 
right- justified  (even  byte)  in  RO. 
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The  expansion  of  .TTYIN  iss 

EMT  340 
BCS  .-2 

while  that  for  .TTINR  is: 

EMT  340 

If  no  characters  or  lines  are  available  when  an  EMT  340  is  executed, 
return  is  made  with  the  C  bit  set.  The  implication  of  these  calls  is 
that  .TTYIN  causes  a  tight  loop  waiting  for  a  character/line  to 
appear,  while  the  user  can  either  wait  or  continue  processing  using 
.TTINR. 

Macro  Calls:  .TTYIN  .char 
.TTINR 

where:  .char  is  the  location  where  the  character  in  R0  is 

stored.  If  not  specified,  the  character  is 
left  in  R0. 

If  the  carry  bit  is  set  when  execution  of  the  .TTINR  request  is 
completed,  it  indicates  that  no  character  was  available;  the  user  has 
not  yet  typed  a  valid  line.  Under  the  F/B  Monitor,  .TTINR  does  not 
return  the  carry  bit  set  unless  bit  6  of  the  Job  Status  Word  was  on 
when  the  request  was  issued  (see  below) . 

There  are  two  modes  of  doing  console  terminal  input.  This  is  governed 
by  bit  12  of  the  Job  Status  Word.  If  bit  12  =  0,  normal  I/O  is 
performed.  In  this  mode,  the  following  conditions  apply: 

1.  The  monitor  echoes  all  characters  typed;  lower  case 
characters  are  converted  to  upper  case. 

2.  CTRL  U  (tU)  and  RUBOUT  perform  line  deletion  and  character 
deletion,  respectively. 

3.  A  carriage  return,  line  feed,  CTRL  Z,  or  CTRL  C  must  be 
struck  before  characters  on  the  current  line  are  available  to 
the  program.  When  carriage  return  is  typed,  characters  on 
the  line  typed  are  passed  one-by-one  to  the  user  program. 
Both  carriage  return  and  line  feed  are  passed  to  the  program. 

4.  ALTMODEs  (octal  codes  175  and  176)  are  converted  to  ESCAPES 
(octal  33) . 

If  bit  12=1,  the  console  is  in  special  mode.  The  effects  are: 

1.  The  monitor  does  not  echo  characters  typed  except  for  CTRL  C 
and  CTRL  O. 

2.  CTRL  U  and  RUBOUT  do  not  perform  special  functions. 

3.  Characters  are  immediately  available  to  the  program. 

4.  No  ALTMODE  conversion  is  done. 

In  special  mode,  the  user  program  must  echo  the  characters  received. 
However,  CTRL  C  and  CTRL  O  are  acted  on  by  the  monitor  in  the  usual 


9-94 


Programmed  Requests 


way.  Bit  12  in  the  JSW  must  be  set  by  the 
cleared  when  control  returns  to  RT-11. 

user  program. 

This 

bit 

is 

CTRL  F  and  CTRL  B  are  not  affected  by  the 
monitor  always  acts  on  these  characters. 

setting 

of 

bit 

12. 

The 

Under  the  F/B  Monitor,  if  a  terminal  input 

request 

is 

made 

and 

no 

character  is  available,  job  execution  is  blocked  until  a  character  is 
ready.  This  is  true  for  both  .TTYIN  and  .TTINR,  and  for  both  normal 
and  special  modes.  If  a  program  really  requires  execution  to  continue 
and  the  carry  bit  to  be  returned,  it  must  turn  on  bit  6  of  the  JSW 
(location  44)  before  the  .TTINR  request.  Bit  6  is  cleared  when  a 
program  terminates. 

Errors : 

Code  Explanation 

0  No  characters  available  in  ring  buffer. 

Example: 

Refer  to  the  example  following  the  description  of  .TTYOUT/.TTOUTR. 


.TTYOUT/.TTOUTR 


9.4.44  .TTYOUT/.TTOUTR 

These  requests  cause  a  character  to  be  transmitted  from  RO  to  the 
console  terminal.  The  difference,  as  in  the  .TTYIN/. TTINR  requests, 
is  that  if  there  is  no  room  for  the  character  in  the  monitor's  buffer, 
the  .TTYOUT  request  waits  for  room  before  proceeding,  while  the 
. TTOUTR  does  not  wait  for  room  and  the  character  in  RO  is  not  output. 

Macro  Calls:  .TTYOUT  .char 

.TTOUTR 

where:  .char  is  the  location  containing  the  character  to 

be  loaded  in  RO  and  printed.  If  not 
specified,  the  character  in  RO  is  printed. 
Upon  return  from  the  request,  RO  still 
contains  the  character. 

If  the  carry  bit  is  set  when  execution  of  the  .TTOUTR  request  is 
completed,  it  indicates  that  there  is  no  room  in  the  buffer  and  that 
no  character  was  output.  Under  the  P/B  Monitor,  .TTOUTR  normally  does 
not  return  the  carry  bit  set.  Instead,  the  job  is  blocked  until  room 
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is  available  in  the  output  buffer.  If  a  job  really  requires  execution 
to  continue  and  the  carry  bit  to  be  returned,  it  must  turn  on  bit  6  of 
the  Job  Status  Word  (location  44)  before  issuing  the  request. 

The  .TTINR  and  .TTOUTR  requests  have  been  supplied  as  a  help  to  those 
users  who  do  not  wish  to  suspend  program  execution  until  a  console 
operation  is  complete.  With  these  modes  of  I/O,  if  a  no-character  or 
no— room  condition  occurs ,  the  user  program  can  continue  processing  and 
try  the  operation  again  at  a  later  time. 


Note: 

If  a  foreground  job  leaves  bit  6  on  in  the  JSW,  any  further  foreground 
.TTYIN  or  .TTYOUT  requests  will  cause  the  system  to  lock  out  the 
background.  Note  also  that  each  partition  has  its  own  JSW,  and 
therefore  cam  be  in  different  terminal  modes  independently. 

Errors : 

Code  Explanation 

0  Output  ring  buffer  full. 

Example : 

As  an  example  of  the  various  terminal  requests,  the  following  program 
is  coded  in  two  ways.  The  program  itself  accepts  a  line  from  the 
keyboard,  then  repeats  it  on  the  terminal. 

The  first  example  uses  .TTYIN  and  .TTYOUT,  which  are  synchronous.  The 
monitor  retains  control  until  both  requests  are  satisfied,  hence  there 
is  no  time  available  for  any  other  processing  while  waiting. 


• MC  ALL  .,V2..,.REG0EF,, TTYIN, .TTYOUT 
..V2.. 

.RESDEF 


9TARTI  MOV  #BUFFER,R1 

CUR  R2 

XNLOOPl  .TTYIN  (Rl)+ 

INC  R2 

CMPB  #12, RB 

BNE  INLOOP 

MOV  #BUFFER,Ri 

OUTLOOPI  .TTYOUT  (Rl>* 

DEC  R2 

BEQ  START 

8R  0UTL00P 


| POINT  R1  TO  BUFFER 
! CLEAR  CHARACTER  COUNT 
! READ  CHAR  INTO  BUFFER 
! BUMP  COUNT 
MAS  LAST  CHAR«LFT 
INO-GET  NEXT 
!  YES-POINT  R 1  TO  BUFFER 
IPRINT  CHAR 
(DECREASE  COUNT 
! OONE  IF  COUNT  •  0 


BUFFER*. 

.END  START 


Rather  than  wait  for  the  user  to  type  something  at  INLOOP  or  wait  for 
the  output  buffer  to  have  available  space  at  OUTLOOP,  the  routine  cam 
be  recoded  using  .TTINR  and  .TTOUTR  as  follows: 


9-96 


Programmed  Requests 


.MCALL  ,.V2,,( .REGOEF..TTVIN, .TTYOUT 

,,V2.. 

.REGDEF 

.MCALL  .TTINR, .TTOUTR,  .EXIT 


STARTI 

MOV 

•BUFFER, Rl 

CLR 

R2 

BIS 

•100,0044 

INLOOPI 

.TTINR 

BCS 

NOCHAR 

CHRINI 

MOVB 

R0, (Rl ) ♦ 

INC 

RS 

CMPB 

R0«  #12 

BNE 

INLOOP 

MOV 

•BUFFER. Rl 

OUTLOOPI 

MOVB 
, TTOUTR 

(R1)»R0 

BCS 

NOROOM 

CHROUTl 

DEC 

R2 

BED 

START 

INC 

Rl 

NOCHAR! 

BR 

OUTLOOP 

.TTINR 

BCC 

• 

CHRIN 

• 

(code 

while 

• 

to  be  ex< 
waiting) 

• 

BR 

NOCHAR 

NOROOMI 

MOVB 

(Rl)iR0 

.TTOUTR 

BCC 

CHROUT 

,REPT 

NOP 

,|NOR 

10 

TYPCITI 

BIC 

# 1 00  »  •••• 

.TTYOUT  (Rl) 

BIS  #100,##«« 


I  POINT  Rl  TO  BUFFER 
I  CLEAR  CHARACTER  COUNT 
I  WE  REALLY  WANT  CARRY  SET 
I  GET  CHAR  FROM  TERMINAL 
INONE  AVAILABLE 
I  PUT  CHAR  IN  BUFFER 
I  INCREASE  COUNT 
f HAS  LAST  CHAR  ■  LF? 
INO-GET  NEXT 
fYES-POINT  Rl  TO  BUFFER 
I  PUT  CHAR  IN  R0 
I  TYPE  IT 

I  NO  ROOM  IN  OUTPUT  BUFFER 
IDECREASE  COUNT 
IOONE  IF  COUNT’0 
I  BUMP  BUFFER  POINTER 
I  AND  TYPE  NEXT 


I  PERIODIC  CHECK  FOR 
I  CHARACTER  AVAILABILITY 
1  GOT  ONE 


I  PERIODIC  ATTEMPT  TO  TYPE 
I  CHARACTER 

I  SUCCESSFUL 


I  THIS  MUST  GO  OUT 
ISO  DON'T  HANG  WHILE 
I  WAITING  FOR  ROOM, 

I  PUT  CHAR 
IRESTORE  NO-WAIT 


BUFFER l  tflLKW  100, 
.END  START 
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.TWAIT 


9.4.45  .TWAIT 

The  .TWAIT  request  suspends  the  user*s  job  for  an  indicated  length  of 
time,  .TWAIT  requires  a  queue  element ,  and  thus,  should  be  taken  into 
account  when  the  .QSET  request  is  executed. 


Macro  call:  .TWAIT  .area,  .time 


where :  . time 


is  a  pointer  to  two  words  of  time 
(high-order  first,  low-order  second) • 


Request  Format 

RO  =>  .area: 


Errors : 

Code  Explanation 

0  No  queue  element  was  availab le. 

Example : 

.TWAIT  can  be  used  in  applications  where  a  program  must  be  only 
activated  periodically.  This  example  will  *wake  up1  every  10  seconds 
to  perform  a  task,  and  then  •sleep1  again. 

• MCALl  ,,V2.## .REGOEF, .TWAIT, .QSET, .EXIT, .PRINT 


..V2., 
a  REGDEF 

601 

•  QSET 

PQAREA.  #7 

1  SET  UR  7  EXTRA  ELEMENTS 

START! 

MOV 

#EMTLST,R0 

1  SET  R0  TO  THE  ARG,  BLOCK 

.TWAIT 

|G0  TO  SLEEP  FOR  10  SECONDS 

BCS 

NOQ 

1  NO  QUEUE  ELEMENT? 

JSR 

PC,  TASK 

IDO  SOMETHING  HERE 

BR 

START 

1  AND  THEN  CYCLE 

QAREAI 

.BLKM 

7*7 

ISPACE  FOR  7  ELEMENTS 

EMTLSTl 

.BYTE 

0,24 

.WORD 

TIME 

TIME! 

.WORD 

0, 10, *60, 

110  SEC0NO  INTERVALS 

TASK! 

1 

1 
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INC 

MPTR 

BIT 

#i,MPTR 

BEQ 

IS 

•PRINT 

•  MSG 

NTS 

PC 

III 

•PRINT 

SMSG1 

RTS 

PC 

MPT*I 

•  WORD 

0 

MSG  1 

•  ASCIZ 

/TICK/ 

MSG  1 1 

•ASCII 
•  EVEN 

/TOCK/ 

NOG ; 

•  EXIT 

•  END 

GO 

.WAIT 


9.4.46  .WAIT 

The  .WAIT  request  suspends  program  execution  until  all  input/output 
requests  on  the  specified  channel  are  completed.  The  .WAIT  request 
combined  with  the  .READ/. WRITE  requests  makes  double-buffering  a 
simple  process. 

.WAIT  also  conveys  information  back  through  its  error  returns.  An 
error  is  returned  if  either  the  channel  is  not  currently  open  or  if 
the  last  I/O  operation  resulted  in  a  hardware  error. 

Macro  Call:  .WAIT  .chan 


Note: 


In  a  F/B  system,  executing  a  .WAIT  when  I/O  is  pending  causes  that  job 
to  be  suspended  and  the  other  job  to  run,  if  possible. 


Request  Format: 


RO 


0 


.chan 


Errors : 

Code  Explanation 

0  Channel  specified  is  not  open. 

1  Hardware  error  occurred  on  the  previous  I/O  operation 

on  this  channel. 


These  error  codes  make  the  .WAIT  request  useful  in  checking  channel 
status . 
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Example : 

For  an  example  of  .WAIT  used  for  I/O  synchronization,  see  the  examples 
in  the  next  section. 

An  example  of  the  use  of  .WAIT  for  error  detection  is  its  use  in 
conjunction  with  .CSIGEN  to  determine  which  file  fields  in  the  command 
string  have  been  specified.  For  example,  a  program  such  as  MACRO 
might  use  the  following  code  to  determine  if  a  listing  file  is 
desired. 


.MCALL 
•  • V2 , . 
.REGOEF 

•  <  V2 . « , , REGDEF 

,  .WAIT, .CSIGEN, .EXIT 

ST  ART  1 

.CSIGEN 

•DSPACE ,  *DE  XT , 

#0  1  PROCESS  COMMAND  STRING 

.WAIT 

•  0 

ICHECK  FOR  FILE  IN  FIRST  FIELD 

BC8 

NOBINARY 

|N0  BINARY  DESIRED 

NOBINARY  1 

.WAIT 

•  1 

ICHECK  FOR  LISTING  SPECIFICATION 

BCS 

NOLISTING 

INO  LISTING  DESIRED 

NOLISTINGl 

.WAIT 

•  3 

ICHECK  FOR  INPUT  FILE  OPEN 

BCS 

ERROR 

INO  INPUT  FILE 

ERROR! 

.EXIT 

OEXTI 

, RAD50 

/MAC/ 

, RAD50 

/OBJ/ 

.RAD50 

/IST/ 

.  WORD 

0 

DSPACE* 

• 

.END 

START 

.WRITE /.WRITC/.WRITW 


9.4.47  .WRITE/. WRITC/.WRITW 


.WRITE 

The  .WRITE  request  transfers  a  specified  number  of  words  from  memory 
to  the  specified  channel.  Control  returns  to  the  user  program 
immediately  after  the  request  is  queued. 
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Macro  Call: 
where : 


WRITE 

•area,  .chan,  .buff,  .went. 

.blk 

buff 

is  the  address  of  the 
used  for  output • 

memory 

buffer  to  be 

went 

is  the  number  of  words 

to  be  written. 

blk 

is  the  number  of  the  block  to 

be  written. 

Request  Format: 


Notes : 


RO  4  .area 


See  the  note  following  .WRITW. 


Errors : 

Code  Explanation 

0  Attempted  to  write  past  end-of-file. 

1  Hardware  error. 

2  Channel  was  not  opened. 


Example : 

Refer  to  the  examples  following  .WRITW. 


.WRITC 


The  .WRITC  request  trams f era  a  specified  number  of  words  from  memory 
to  a  specified  channel.  Control  returns  to  the  user  program 
immediately  after  the  request  is  queued.  Execution  of  the  user 
program  continues  until  the  .WRITC  is  complete,  then  control  passes  to 
the  routine  specified  in  the  request.  When  am  RTS  PC  is  encountered 
in  the  routine,  control  returns  to  the  user  program. 


Macro  Call: 
where : 


.WRITC  .area,  .cham,  .buff,  .went,  .ertn,  .blk 

.buff  is  the  address  of  the  memory  buffer  to  be 

used  for  output. 

.went  is  the  number  of  words  to  be  written. 


.ertn  is  the  address  of  the  completion  routine  to 

be  entered. 

.blk  is  the  number  relative  to  the  start  of  the 

file,  not  block  0  of  the  device.  The  monitor 
trams lates  the  block  supplied  into  am 

absolute  device  block  number.  The  user 

program  normally  updates  .blk  before  it  is 
used  again. 
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Request  Format: 


RO  4  .area: 


11  I 

TBit 


.chan 


.buff 

.went 


.ertn 


When  entering  a  .WRITC  completion  function  the  following  are  true: 


1.  RO  contains  the  channel  status  word  for  the  operation.  If 
bit  0  of  RO  is  set,  a  hardware  error  occurred  during  the 
transfer.  The  data  may  not  be  reliable. 

2.  Rl  contains  the  octal  channel  number  of  the  operation.  This 
is  useful  when  the  same  completion  function  is  to  be  used  for 
several  different  transfers. 


Notes : 

See  the  note  following  .WRITW. 

Errors : 

Code  Explanation 

0  End-of-file  on  output.  Tried  to  write  outside  limits 

of  file. 

1  Hardware  error  occurred. 

2  Specified  channel  is  not  open. 


Example : 

Refer  to  the  examples  following  .WRITW. 

.WRITW 

The  .WRITW  request  transfers  a  specified  number  of  words  from  memory 
to  the  specified  channel.  Control  returns  to  the  user  program  when 


the  .WRITW  is  complete. 

Macro  Call:  .WRITW  .area,  chan,  .buff,  .went,  .blk 

where:  .buff 

is  the  address  of  the  buffer  to  be  used 
output. 

for 

•went 

is  the  number  of  words  to 
number  must  be  positive. 

be  written. 

The 

.blk 

is  the  number  of  the  block 

to  be  written. 
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Request  Formats 


RO  4  .areas 


11  I  .chan 

Tblk 

.buff 

.went 

o - 


Notes 

Upon  return  from  any  of  the .WRITE  EMTs,  RO  contains  the  number  of 
words  written.  If  an  attempt  is  made  to  write  past  end-of-file  but 
the  request  can  be  partially  fulfilled,  the  output  word  count  is 
shortened  and  an  error  is  returned  (except  .READ,  which  gives  an  error 
only  if  no  words  can  be  transferred).  Note  that  a  write  will  be  done, 
and  a  completion  routine,  if  any,  will  be  entered,  unless  the  request 
cannot  even  be  partially  filled  (shortened  word  count=0) . 

Errors  s 

Code  Explanation 

0  Attempted  to  write  past  EOF. 

1  Hardware  error. 

2  Channel  was  not  opened. 


Examples  s 


The  following  routine  illustrates  the  differences  between  the  three 
types  of  .RE AD/. WRITE  requests  and  is  coded  in  three  ways,  each  using 
a  different  mode  of  monitor  I/O.  The  routine  itself  is  a  simple 
program  to  duplicate  a  paper  tape. 

In  the  first  example,  .READW  and  .WRITW  are  used.  The  I/O  is 
completely  synchronous,  with  each  request  retaining  control  until  the 
buffer  is  filled  (or  emptied) . 

.MCALl  . • V2 . . , .REGDEF, .FETCH, .READ W, , WRIT H 
.MCAU  .ENTER,  .LOOKUP,  .PRIM,  .EXIT,  .CLOSE,  .WAIT 
•  • V2 » . 

. RE60EF 


ERRHD»52 


START  I 


LOOPI 


.FETCH  #H5PACE,*PRNAME 
8CS  FERR 

MOV  R0,R2 

.FETCH  R2,»PPNAME 
BCS  FERR 

MOV  # ARE  A , R5 

CIR 
MOV 
.ENTER 
BCS 

.LOOKUP 
BCS 

clr 

, RE AON 

BCS 

.HRITH 


;fiET  PR  HANDLER 

IPR  NOT  AVAILABLE 

»R0  HAS  NEXT  FREE  LOCATION 

IGET  PP  HANDLER 

I  NOT  AVAILABLE 

IEMT  ARGUMENT  AREA 

IRA  18  OUTPUT  CHANNEL!  0 

IRS  IS  INPUT  CHANNEL  II 

I  ENTER  THE  FILE 

I50ME  ERROR  IN  ENTER 

I  LOOKUP  FILE  ON  CHANNEL  t 

I  ERROR  IN  LOOKUP 

IUSE  R 1  AS  BLOCK  NUMBER 

. ,  R 1  IREAD  ONE  BLOCK 


R« 

#1,R3 

RS, RA, PPPNAME 
ENERR 

R5, R3, APRNAME 
LKERR 
R1 

R5,R3,#BUFF,#256 
ROERR 

R5,RA,#BUFF,#256.,Rl  IWRITE  THAT  BLOCK 
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BC  5 

UTERR 

INC 

R1 

i bump  block,  notei  this  is 
inot  necessary  for  non-file 

(DEVICES  IN  GENERAL.  IT  IS 
(USED  HERE  AS  AN  EXAMPLE  OF 

(A  general  technique. 

SR 

LOOP 

(KEEP  GOING 

ROERRt 

T5TB 

ERRWD 

(ERROR,  IS  IT  EOF? 

9EQ 

IS 

(YES 

.PRINT 
•  EXIT 

PRDMSG 

(NO,  hard  read  error 

IS! 

.CLOSE 

R3 

(CLOSE  INPUT  AND  OUTPUT 

.CLOSE 

.EXIT 

R* 

(AND  EXIT, 

WTERRl 

.PRINT 
•  EXIT 

PWTMSG 

PRNAMEI 

.  RAD50 

/PR  / 

(NOTE  THAT  PR  NEEDS  NO  FILE  NAME 

.WORD 

0 

(FILE  NAME  NEED  ONLY  BE  0. 

PPMAMEl 

.RAD50 

/PP  / 

.WORD 

0 

FERRl 

.PRINT 

PFNSG 

(ERROR  ACTIONS  GO  HERE.  IT  IS 

.EXIT 

(GENERALLY  UNDESIRABLE  TO 

ENERRl 

.PRINT 

PEMSG 

(EXECUTE  A  HALT  OR  RESET 

.EXIT 

(INSTRUCTION  ON  ERROR, 

LKERR» 

.PRINT 
•  EXIT 

PLMSG 

FMSGI 

.ASCII 

/NO  DEV 

ICE?/ 

EMSGl 

,  ASCIZ 

/ENTRY 

ERROR?/ 

LMSGI 

.ASCII 

/LOOKUP 

ERROR?/ 

RDMSGl 

.ASCIZ 

/READ  ERROR?/ 

WTMSGl 

.ASCII 

•  EVEN 

/WRITE 

ERROR?/ 

AREA  1 

,BLM 

IB 

BUFFI 

.BLKW 

256 . 

HSPACE* 

• 

•  END 

START 

The  same  routine  can  be  coded  using  .READ  and  .WRITE  as  follows.  The 


.WAIT 

request 

is  used  to 

determine  if  the  buffer  is  full  or  empty 

prior 

to  its  use. 

.MCALL 

,.V2.., .REGDEF, 

.FETCH, .READ, .WRITE 

.mcall 

» « V2, . 

. REGDEF 

ERRwO*52 

.ENTER, .LOOKUP, 

•PRINT, .EXIT, .CLOSE, .WAIT 

STARTl 

.FETCH 

PH8PACE,PPRNAME 

(GET  PR  HANDLER 

BCS 

FERR 

(PR  not  available 

MOV 

RB,R2 

|R0  HAS  NEXT  FREE  LOCATION 

.FETCH 

R2 , PPPNAME 

(GET  PP  HANOLER 

BCS 

FERR 

(NOT  AVAILABLE 

MOV 

PARE A , R5 

(EMT  ARGUMENT  AREA 

CLR 

R# 

(R<1  IS  OUTPUT  CHANNEL  (  0 

MOV 

PI,R3 

(R3  IS  INPUT  CHANNEL  11 

.enter 

R5,R«, PPPNAME 

(ENTER  THE  FILE 
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LOOP  * 


RDERRl 


I QERR t 

PRNAMEI 

PPNAMEI 

FERRl 

ENERRI 

LKERRI 

FM8GI 

EMSGl 

LHSGI 

IOMSGl 

WTMSGl 

AREA  I 
BUFFI 
HSPACE*. 


BC8  ENERR  /SOME  ERROR  IN  ENTER 

.LOOKUP  R5,R3,*PRNAME  ILOOKUP  FILE  ON  CHANNEL  l 


ecs 

LKERR 

1 ERROR  IN  LOOKUP 

clr 

R 1 

IUSE  Ri  AS  BLOCK  NUMBER 

.READ 

R5, R3,#BUFF,#256 

>.,R1  1  READ  *  BUFFER 

BCS 

RDERR 

.WAIT 

R3 

IWAIT  FOR  BUFFER 

BCS 

I0ERR 

f ERROR  HERE  IS  HARD  ERROR 

.WRITE 

R5. RA. FBUFF , *25t 

>.,R1  IWRITE  TTHE  BUFFER 

BCS 

I0ERR 

II/O  ERROR 

INC 

R1 

8R 

LOOP 

IKEEP  GOING 

TSTB 

ERRWD 

IERROR,  IS  IT  EOF? 

0NE 

I0ERR 

f NO r  HARO  ERROR 

.CLOSE 

R3 

1  CLOSE  INPUT  AND  OUTPUT 

.CLOSE 

R« 

.EXIT 

1  ANU  EXIT, 

.PRINT 

PIOHSG 

1  NO #  HARD  READ  ERROR 

.EXIT 

, R AO50 

/PR  / 

INOTE  THAT  PR  NEEDS  NO  FILE  NAME 

.WORD 

0 

IFILE  NAME  NEED  ONLY  BE  0. 

, R *050 

/PP  / 

.WORO 

0 

.PRINT 

#PMSG 

IERROR  ACTIONS  GO  HERE.  IT  IS 

.EXIT 

1  GENERALLY  UNDESIRABLE  TO 

.PRINT 

#EM$G 

f EXECUTE  A  HALT  OR  RESET 

.EXIT 

1  INSTRUCT I ON  ON  ERROR. 

.PRINT 

•  LMSG 

.EXIT 

.ASCIZ 

/NO  DEVICE?/ 

.ASCII 

/ENTRY  ERROR?/ 

.ASCIZ 

/LOOKUP  ERROR?/ 

.ASCIZ 

"I/O  ERROR?" 

.ASCIZ 

/WRITE  ERROR?/ 

.EVEN 

.BLKW 

10 

.BLKW 

258. 

.END 

START 

.READ  and  .WRITE  are  also  often  used  for  double-buffered  I/O.  The 
basic  double-buffering  algorithm  for  input  is: 


Explanation 


LOOP: 


READ 

BUFFER  1 

Fill  BUFFER  1 

WAIT 

BUFFER  1 

Wait  for  BUFFER  1  to  fill 

READ 

BUFFER  2 

Start  filling  BUFFER  2 

USE 

BUFFER  1 

Process  BUFFER  1  while  BUFFER 

2 

fills 

WAIT 

BUFFER  2 

Wait  for  BUFFER  2  to  fill 

READ 

BUFFER  1 

Start  filling  BUFFER  1 

USE 

BUFFER  2 

Process  BUFFER  2  while  BUFFER 

1 

fills 

BR 

LOOP 
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Correspondingly,  the  basic  double-buffering  algorithm  for  output  is: 

Explanation 


FILL  BUFFER  1 

Prepare  BUFFER  1  for  output 

LOOP: 

WRITE  BUFFER  1 

Start  emptying  BUFFER  1 

FILL  BUFFER  2 

Fill  BUFFER  2  while  BUFFER  1 
empties 

WAIT  BUFFER  1 

Wait  for  BUFFER  1  to  empty 

WRITE  BUFFER  2 

Start  emptying  BUFFER  2 

FILL  BUFFER  1 

Fill  BUFFER  1  while  BUFFER  2 
empties 

WAIT  BUFFER  2 

BR  LOOP 

Wait  for  BUFFER  2  to  empty 

This  example  program  can  be  coded  using  completion  routines  via  .RE ADC 
and  .WRITC  as  follows.  Once  the  initial  read  is  performed,  the 
remainder  of  the  I/O  is  performed  by  the  completion  routines. 

.MCALL  ,  ,V£.., .REGOEF,  .FETCH, , RE ADC, .WRITC 
•MCALL  .ENTER, .LOOKUP,. PRINT,, EXIT, .CLOSE,  .WAIT 
. »  V  £ » . 

, REGOEF 

ERRW0«S2 


start: 

.FETCH 

•hspace.pprname 

> GET  PR  HANDLER 

8CS 

FERR 

IPR  NOT  AVAILABLE 

MOV 

R0,R2 

|R0  HAS  NEXT  FREE  LOCATION 

.FETCH 

R2 , PPPNAME 

1  GET  PP  HANDLER 

80S 

FERR 

»N0T  AVAILABLE 

MOV 

•ARE A , R5 

IEMT  ARGUMENT  AREA 

CLR 

R4 

IRA  IS  OUTPUT  CHANNEL!  0 

MOV 

•  1 ,  PS 

IR3  IS  INPUT  CHANNEL  11 

.ENTER 

R5 , R4 »  #PPN A  ME 

1  ENTER  THE  FILE 

BCS 

ENERR 

ISOME  ERROR  IN  ENTER 

.LOOKUP 

R5,R3,*PRNAME 

1  LOOKUP  FILE  ON  CHANNEL  1 

BCS 

LKERR 

terror  IN  LOOKUP 

CLR 

RI 

TUBE  Rl  AS  BLOCK  NUMBER 

loop: 

CLR 

DFLG 

1  CLEAR  DONE/ERROR  FLAG 

.REAOC 

RS, R3 , PBUFF , #256 

• , ARDCOMP, R 1  | RE AO  ONE  BLOCK 

BCS 

EOF 

;no  error  will  happen  HERE 

1SI 

TST 

DFLG 

I00NE  FLAG  SETT 

BEQ 

IS 

INO,  WAIT  FOR  IT  TO  BE  SET. 

SMI 

I0ERR 

IVES,  BUT  HARO  ERROR  OCCURRED 

EOF! 

.CLOSE 

R3 

ICLOSE  INPUT  AND  OUTPUT  CHANNELS 

.CLOSE 

R4 

.EXIT 

iall  done 

.enabl 

L8B 

R0C0MPI 

ROR 

RS) 

1  IF  BIT  B  SET 

BCS 

RDERR 

1  AN  ERROR  occurred. 

.WRITC 

R5,R4,#BUFF,#25B 

. , AWRCOMP , R 1  IWRITE  THAT  BLOCK 

BCC 

es 

terror  here  is  hardware 

ROERRl 

MOV 

•  ■1 , DFLG 

IF LAG  THE  ERROR 

SSI 

RTS 

PC 

WRCOMPt 

ROR 

R0 

BCS 

ROERR 

I  HARDWARE  ERROR 

INC 

Rl 

1  BUMP  BLOCK. 

.REAOC 

R5,R3,#BUFF , *£56 

. , PRDCOMP, Rl 

8CC 

38 

|N0  ERROR 

TST8 

ERRWD 

1  EOF? 
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BNE 

ROERR 

(NO,  HAND  ERROR 

3SI 

INC 

OFLC 

(SAY  wE'RE  DONE 

RTS 

PC 

.DSABL 

LSB 

OFLGl 

,  WORD 

e 

PRNAMEI 

.RAUSB 

/PR  / 

INOTE  THAT  PR  NEEDS  NO  FILE 

.WORD 

e 

IFILE  NAME  NEED  ONLY  BE  0 , 

PPNAMEI 

.RAO50 

/pp  / 

.WORD 

0 

I0ERRI 

.PRINT 

.EXIT 

*I0MSG 

FERRI 

.PRINT 

•  FMSG 

(ERROR  ACTIONS  GO  HERE,  IT 

•  EXIT 

(generally  undesirable  TO 

ENERRl 

.PRINT 

#EM#G 

1  EXECUTE  A  HALT  OR  RESET 

.EXIT 

I  INSTRUCTION  ON  ERROR. 

LKERRl 

.PRINT 

.EXIT 

•  LMSG 

FMSGl 

.ASCII 

/NO  DEVICE?/ 

EMSGI 

, A  SC  I Z 

/ENTRY  ERROR?/ 

LMSfi: 

.  A8CIZ 

/LOOKUP  ERROR?/ 

I QM5G  8 

.ASCII 

.EVEN 

"I/O  ERROR?" 

AREA  I 

,BIKW 

10 

BUFFI 

,BLKW 

254 . 

HSPACEi 

« 

.END 

START 

\ 


The  following  example  incorporates  the  .LOOKUP,  .READW,  and  .CLOSE 
requests.  The  program  opens  the  file  RT11.MAC  which  is  on  the  system 
device,  SYs,  for  input  on  channel  0.  The  first  block  is  read  and  the 
file  is  then  closed. 

."CALL  , .V2.,, .REGOEF, , CLOSE, .LOOKUP 

.MCALL  .PRINT, ,1X1 T, .READ*, .FETCH 

..V2.. 

• RE6DEF 


STARTl 

MOV 

•LIST, R5 

|EMT  ARGUMENT  LIST  POINTER 

CLR 

R« 

(BLOCK  NUMBER 

CLR 

RJ 

ICHANNIL  4 

.FETCH 

•CORADD.PFPTR 

(FETCH  DEVICE  HANDLER 

sec 

28 

MOV 

4FETMSG, R0 

IFETCH  ERROR 

1SI 

.PRINT 

(PRINT  ERROR  MESSAGE 

.EXIT 

2*1 

.LOOKUP 

R5, RS, *FPTR 

(LOOKUP  FILE  ON  CHANNEL  0 

BCC 

SS 

MOV 

•LKMSG.R0 

(PRINT  FAILURE  MESSAGE 

8R 

IS 

SSI 

.READW 

R5,RS,«BUFF,#25t 

>,,RA  (REA  ONI  BLOCK 

BCC 

44 

MOV 

4RDMSG, RB 

(READ  ERROR 

BR 

IS 

4*1 

.CLOSE 

R3 

(CLOSE  THE  CHANNEL 

.EXIT 

LISTI 

.blkw 

5 

(LIST  FOR  EMT  CALLS 

FPTRI. 

,  RAD50 

/SY  RTll  MAC/ 

(RAD50  OF  F IEL  NAME, DEVICE 

FETMSGI 

•  A8CIZ 

/FETCH  FAILED/ 

(ASCII  MESSAGES 

LKMSGl 

.ASCII 

/LOOKUP  FAILED/ 
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ROMSGt 

•ASCII 

/READ  FAILED/ 

.EVEN 

CQRAD0I 

•  BLKW 

2000 

ISRACE  FOR  LARGEST  HANDLERS 

BUFF* , 

.END 

START 

9.5  CONVERTING  VERSION  1  MACRO  CALLS  TO  VERSION  2 

As  mentioned  in  the  introduction  of  this  chapter ,  RT-11  Version  2 
supports  a  slightly  modified  format  for  system  macro  calls  than 
Version  1.  This  section  details  the  conversion  process  from  the 
Version  1  format  to  Version  2. 


9.5.1  Macro  Calls  Requiring  No  Conversion 
Version  1  macro  calls  which  need  no  conversion  are: 


•CSIGN 

. RCTLO 

.CSISPC 

.RE  LEAS 

.DATE 

.SETTOP* 

.DSTATUS 

.SRESET 

.EXIT 

.TTINR** 

.FETCH 

. TTOUTR 

.HRESET 

.TTYIN 

.LOCK 

.TTYOUT 

.PRINT 

.QSET 

.UNLOCK 

♦Provided  location  50 

is  examined  for  the 

**Except  in  F/B  System. 

9.5.2  Macro  Calls  Which  May  Be  Converted 

The  following  Version  1 

macro  calls  may  be 

.CLOSE 

.RENAME 

•DELETE 

. REOPEN 

.ENTER 

.SAVESTATUS 

.LOOKUP 

.WAIT 

.READ 

.WRITE 

The  general  format  of  the  VI  macro  is: 

.PRGREQ  .chan,  .argl  . arg2 , . . . argn 


In  this  form,  .chan  is  an  integer  between  0  and  17  (inclusive),  and 
is  not  a  general  assembler  argument.  The  channel  number  is  assembled 
into  the  EMT  instruction  itself.  The  arguments  argl-argn  are  always 
pushed  either  into  RO  or  on  the  stack. 

The  V2  equivalent  of  the  above  call  is: 


.PRGREQ  .area,  .chan,  .argl,. .. .argn 


9-108 


Programmed  Requests 


In  the  V2  call,  the  .chan  argument  can  be  any  legal  assembler 
argument ;  it  need  not  be  in  the  range  0  to  17  (octal) ,  but  should  be 
in  the  range  0-377  (octal),  .area  points  to  a  memory  list  where  the 
arguments  argl...argn  will  go. 

As  am  example,  consider  a  .READ  request  in  both  forms: 


VI: 
V2 : 


.READ  5 , #BUFF, #256 . , BLOCK 
.READ  # AREA, #5, #BUFF, #256. , BLOCK 


AREA:  .WORD  0  ; CHANNEL/FUNCTION  CODE  HERE 

.WORD  0  ; BLOCK  NUMBER  HERE 

.WORD  0  ; BUFFER  ADDRESS  HERE 

.WORD  0  ;WORD  COUNT  HERE 

.WORD  0  ;A  1  GOES  HERE. 

Thus,  the  difference  in  the  calls  is  that  in  Version  2  the  channel 
number  becomes  a  legal  assembler  argument  and  the  .area  argument  has 
been  added. 

Following  is  a  complete  list  of  the  conversions  necessary  for  each  of 
the  EMT  calls.  Both  the  Version  1  and  Version  2  formats  are  given. 
Note  that  parameters  inside  []  are  optional  parameters.  Refer  to  the 
appropriate  section  in  this  chapter  for  more  details  of  each  request. 


Version 

Programmed  Request 

VI: 

.DELETE  .chan, .dblk 

V2: 

.DELETE  . area, .chan,. dblk, [.count] 

VI: 

.LOOKUP  .chan,. dblk 

V2: 

.LOOKUP  .area, .chan, .dblk, [.count] 

VI: 

. ENTER  . chan , . dblk , [ . length] 

V2 : 

.ENTER  .area,. chan,. dblk, [.length] , [. 

VI: 

.RENAME  .chan,. dblk 

V2 : 

.RENAME  .area,. chan,. dblk 

VI: 

.SAVESTAT  .chan,.cblk 

V2 : 

.SAVESTAT  .area,. chan,. cb lk 

VI: 

.REOPEN  .chan,.cblk 

V2 : 

.REOPEN  .area, .chan, .cblk 

VI: 

.CLOSE  .chan 

V2 : 

.CLOSE  .chan 

VI: 

. READ/ . READW  .chan, .buff , .went, .blk 

V2 : 

. READ/ . READW  .area, .chan, .buff, .went. 

VI: 

.RE ADC  .chan, .buff , .went, .ertn,. blk 

V2 : 

. READC  . area , .buff, .went,. ertn , . b lk 

VI: 

. WRITE/. WRITW  .chan,. buff,. went,. blk 

V2 : 

. WRITE/. WRITW  .area,. chan,. buff,. went 
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Vis  .WRITC  . chan , . buf f , .went , . ertn , .  blk 

V2s  .WRITC  .area,. chan,. buff ,. went,. ertn,. blk 

VI i  .WAIT  .chan 

V2s  .WAIT  .chan 

Important  features  to  keep  in  mind  for  Version  2  calls  are : 

1.  Version  2  calls  require  the  .area  argument,  which  points  to 
the  area  where  the  other  arguments  will  be. 

2.  Enough  memory  space  must  be  allocated  to  hold  all  the 
required  arguments. 

3.  .chan  must  be  any  legal  assembler  argument,  not  just  an 
integer  between  0-17  (octal) . 

4.  Blank  fields  are  permitted  in  the  Version  2  calls.  Any  field 
not  specified  (left  blank)  is  left  alone  in  the  argument 
block. 


CHAPTER  10 


EXPAND  UTILITY  PROGRAM 


EXPAND  is  an  RT-11  system  program  which  processes  the  macro  references 
in  a  macro  assembly  language  source  file.  EXPAND  accepts  a  subset  of 
the  complete  macro  language  and,  using  the  system  library  file 
SYSMAC.8K,  produces  an  output  file  in  which  all  legal  macro  references 
are  expanded  into  macro-free  source  code.  EXPAND  is  normally  used 
with  ASEMBL,  the  RT-11  assembler  designed  for  minimum  memory 
configurations  (refer  to  Chapter  11) . 

10 . 1  LANGUAGE 

EXPAND  simply  copies  its  input  files  to  .its  output  file  unless  it 
encounters  any  of  the  following  directives  (see  Chapter  5  for  more 
information  about  these  directives) s 


1.  .MCALL 

Directs  EXPAND  to  search  the  file 
SY : SYSMAC • SML  to  find  the  macro  names  listed 
in  the  .MCALL  directive.  If  the  macro  names 
are  found ,  EXPAND  stores  their  definitions  in 
its  internal  tables. 

2.  .MACRO 

Directs  EXPAND  to  copy  a  macro  definition 
from  the  user's  input  file  into  the  internal 
tables. 

3.  .name 

If  .name  is  the  name  of  a  macro  defined  in 
either  a  .MCALL  or  .MACRO  directive,  then 
.name  is  expanded  according  to  the  definition 
stored  for  it  in  the  EXPAND  internal  tables. 

4.  . ENDM 

If  encountered  while  storing  a  macro 
definition,  the  .ENDM  directive  terminates 
the  definition.  It  is  not  recognized  outside 
macro  definitions. 

10.2  RESTRICTIONS 

Unlike  the  full  macro  assembler  (MACRO) ,  EXPAND  only  expands  macros 
that  observe  the  following  restrictions: 
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1.  The  following  directives  may  not  be  used: 


.ERROR  .NARG 

.IF  DIF  .NCHR 

.IF  IDN  . NTYPE 

. IRP  .PRINT 

• IRPC  .REPT 

.MEXIT 


2.  Macros  cannot  be  nested.  Recursive  macros  that  call 
themselves  directly  or  indirectly  are  illegal  and  cause  an 
error  message. 


3.  Macros  cannot  be  redefined.  Once  a  name  has  been  used  for  a 
macro  name,  it  cannot  be  used  again  in  the  program  for  a 
macro  or  symbol  name. 


4.  Macro  names  must  begin  with  a  dot  (•).  If  the  dot  is  missing, 
an  error  message  is  printed. 


5.  Dummy  argument  names  must  begin  with  a  dot  (•)•  Such  names 
cannot  be  used  as  dummy  argument  names  in  the  macro  but  can 
be  used  for  other  purposes  outside  of  the  macro. 


6.  The  backslash  operator  is  not  available. 

7.  Automatically  created  symbols  are  not  available. 

8.  No  more  than  30  arguments  may  be  used  in  any  MACRO  directive. 


10.3  CALLING  AND  USING  EXPAND 
To  run  EXPAND,  type: 

R  EXPAND 

in  response  to  the  dot  printed  by  the  Keyboard  Monitor.  EXPAND 
responds  with  an  asterisk  indicating  that  it  is  ready  to  accept  a 
command  string.  A  command  string  must  be  of  the  following  form: 

*ofile=ifilel,ifile2, • • • ,ifile6 

ifile2  through  ifile6  are  optional.  Each  file  specification  follows 
the  general  RT-11  command  string  syntax  (dev:filnam.ext) .  The  default 
value  for  each  file  specification  is  noted  below: 


I/O  File 

Dev 

Ext 

— 

■■  ■" 

ofile 

DK 

PAL 

ifilel,.... 

device  used 

MAC 

ifile6 

for  last  source 
file  specified 
or  DK 

Type  CTRL  C  to  halt  EXPAND  and  return  control  to  the  monitor.  To 
restart  EXPAND,  type  R  EXPAND  or  the  REENTER  command  in  response  to 
the  monitors  dot. 
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EXPAND  copies  sequentially  the  specified  input  files  to  the  specified 
output  file  until  a  macro  directive  is  encountered,  EXPAND  then 
changes  the  macro  directive  to  a  comment  by  inserting  a  semicolon  so 
that  it  will  not  be  seen  later  by  the  assembler  (usually  ASEMBL) • 

If  the  directive  is  • MCALL ,  EXPAND  searches  the  system  library  file 
(SYSMAC. 8K)  for  the  requested  macro  definitions.  The  requested 
definitions  are  then  included  in  the  user’s  program  in  the  order  in 
which  they  are  found  in  the  library. 

For  the  .MACRO  directive ,  EXPAND  reads  each  line  following  the 
directive  up  to  the  next  .ENDM  directive.  Each  line  is  stored  in  the 
internal  definition  table  and  then  changed  to  a  comment  in  the  output 
file  so  that  it  is  not  processed  later  by  the  assembler.  Also,  any 
occurrence  of  a  macro  argument  name  within  the  definition  is  flagged 
internally  so  that  it  can  be  replaced  by  the  real  argument  value 
whenever  the  macro  is  later  referenced. 

For  macro  references,  EXPAND  locates  the  stored  macro  definition  in 
its  internal  tables,  binds  the  actual  argument  values  to  the  argument 
names,  and  changes  the  macro  reference  to  a  comment  line.  EXPAND  then 
begins  copying  the  stored  definition  to  the  output  file.  Whenever  a 
macro  argument  name  is  encountered  in  the  definition,  it  is  replaced 
by  the  corresponding  actual  argument  value. 

Examples : 

The  following  are  examples  of  input  and  corresponding  EXPAND  output. 


INPUT 

OUTPUT 

Njlll 

*1«X1 

SP*%6 

PC*X? 

PC"X7 

.MACHO  .CALL  .SUB* 

t 

, mac«o 

.Call  . 

SUB* 

J3R  f»C».3UBR 

1 

JSR  Pc» 

.  SUSP 

.endm 

1 

.ENDM 

.mcall  .lookup. .read 

f 

•mcall 

.LOOKUP 

,  .READ 

i .macro 

.LOOKUP 

.AREA, 

.CHAN, .OEVBLK, . 

I.IF  NOP 

...V2 

I.IF  NB 
> 

.CHAN 

MOV 

. CHAN , xz 

; .ENOC 

1 

EMT 

*O«20+.AREA> 

I. IFF 
I.IF  NB 

1 

.area 

MOV 

,AfteA,X0 

1 

MQV 

M00,  (0) 

1  .ENOC 
; ,  IF  N8 

1 

.CHAN 

MOVb 

•  CM AN , (0) 

1 , EWOC 

I. IF  N8 
> 

.DEVBLK 

MOV 

.OEVBLK, 2. (0) 

| .ENOC 
I.IF  NB 

1 

,SPF 

MOV 

. SPF , 4 . (0) 

1 «  JfF 

1 

clR 

4.(0) 

I.EnOC 
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STAC*! 

BUFRl 

INSlKi 

START! 

At 

BS 


.CSECT  MAIN 
•  61001  SURT 
.BLK*  100 
.BLM  100 
.BLKW  10 
MOV  «3TAClf»3F 
MOV  Ri,.(3P) 
.CALL  SORT 
.LOOKUP  0,*INBLK 


i 

£MT 

*0375 

I.EnOC 
; .Enom 

i .macro 

.READ 

.AREA, 

, CMAN, .BUFF, , 

I.IF  NOF  ...V2 

I.IF  NS 

1 

.  WCNT 

MOV 

.WCNT , X0 

i ,endc 

> 

MOV 

*li-(6.) 

1 

MOV 

.BUFF, -(6.) 

1 

MOV 

.CMAN, -(6.) 

1 

EMT 

*O«200+, ARE 

1  •  IFF 

I.IF  N8 

1 

.AREA 

MOV 

.  AREA , %0 

1 

MOV 

*4000 , (0) 

I.ENOC 

|,IF  NB 

1 

.cman 

MOVB 

.CHAN, (0) 

I.ENOC 

I.IF  NB 

1 

.blk 

MOV 

.BLK, 2. (0) 

I.ENOC 

I.IF  NB 

1 

.BUFF 

MOV 

.BUFF, 4. (0) 

I.ENOC 

I.IF  NB 

1 

.WCNT 

MOV 

.WCNT, 6. (0) 

I.ENOC 

1 

MOV 

Mi8.  (0) 

1 

EMT 

*0375 

I.ENOC 

i.enom 

STACK! 

■CSECT 

.globl 

•  BLK  w 

MAIN 

3QRT 

100 

8UFRI 

•  BLK  W 

100 

INBLKt 

•  BLK  A 

10 

START! 

MOV  R8TACK.5P 

Al 

MOV  Rl 

#-(SP) 

8 !  I 

.CALL 

Sort 

J8R  Pc 

*  SORT 

1  .LOOKUP  0,#INBLK 

•IF  NOF  ...V2 
,  IF  NB  #INBLK 


#.8LK 
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CUR  *1  J BLOCK  NUMBER 
.READ  0,#BUFR,#258.,R1 


HALT 

•ENO  STaRT 


MOV 

"INBLK'XB 

.ENDC 

EMT 

AQ«20*0> 

.iff 

.IF  NB  0 

MOV 

0#%0 

.ENDC 

MOV 

R400, C0) 

.IF  Ng  *INBL* 

movb 

RINBUK. (0) 

.ENDC 

.IF  Nb 

MOV 

*  2 . (0) 

.ENDC 
.IF  NB 

MOV 

»4, (0) 

.IFF 

CCR 

4.(0) 

.ENDC 

EMT 

AQ37S 

.ENDC 

CCR  Rl 

1  BLOCK 

NUMBER 

1  .READ  8 

,*bufh. 

*256, ,R1 

.IF  NDF  ,  ,  ,  V2 
.IF  NB  Rl 

MOV 

Rl.%0 

.ENDC 

MOV 

*1 » • (6 • ) 

MOV 

*256, ,-(6.) 

MOV 

R8UFR,-(6.) 

EMT 

AQ«200+0> 

.IFF 

.IF  NB  0 

MOV 

0  1  %0 

MOV 

R4000 , (0) 

.ENDC 

.IF  NB  «BUFR 

MOVB 

RBUFR, (0) 

.ENDC 

.IF  NB 

MOV 

*2. C0j 

.ENDC 

.IF  NB  *286. 

MOV 

*258, ,4.(0) 

.  ENOC 
.IF  NB  Rl 

MOV 

Ri»8,  (0) 

.ENOC 

MOV 

*1 » 8, (0) 

.ENDC 

EMT 

AQ375 

halt 


.end  start 
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10.4  EXPAND  ERROR  MESSAGES 

The  following  messages  are  caused  by  fatal  errors  detected  by  EXPAND. 
They  print  on  the  console  terminal  and  cause  EXPAND  to  restart: 

Message  Explanation 

?BAD  SWITCH?  An  unrecognized  command  string 


switch  was  specified. 

? INPUT  ERROR? 

Hardware  error  in  reading  an  input 
file. 

? INSUFFICIENT  CORE? 

Not  enough  memory  to  store  macro 
definitions. 

?MISSING  END  IN  MACRO? 

End  of  input  was  encountered  while 
storing  a  macro  definition; 
probably  missing  an  .ENDM. 

?NO  INPUT  FILE? 

There  must  be  at  least  one  input 
file. 

?OUTPUT  DEVICE  FULL? 

No  room  to  continue  writing  output; 
try  to  compress  the  device  with 
PIP. 

? WRONG  NUMBER  OF  OUTPUT  FILES? 

There  must  be  exactly  one  output 
file. 

The  following  errors  are  non- fatal  but  indicate  that  something  is 
wrong  in  the  input  file(s).  These  errors  appear  in  the  output  file  as 
a  line  in  the  following  form: 

?***  ERROR  ***  message 

After  each  run  of  EXPAND,  the  total  number  of  non-fatal  errors  is 
printed  on  the  console  terminal. 


Message 

Explanation 

BAD  MACRO  ARG 

The  macro  argument  is  not  formatted 
correctly. 

LINE  TOO  LONG 

A  line  has  become  longer  than  132 
characters . 

MACRO  ALREADY  DEFINED 

A  macro  was  defined  more  than  once. 

MACRO (S)  NOT  FOUND 

Macros  listed  in  an  .MCALL 
statement  were  not  found  in 
SYSMAC.8K  (make  sure  SYSMAC.8K  is 
present  on  system) . 

MISSING  COMMA  IN  MACRO  ARG 

Found  spaces  or  tabs  within  a  macro 
argument;  try  using  brackets 
around  the  argument,  e.g.,  <arg 
with  spaces >. 
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MISSING  DOT 

A  macro  name  or  argument  name  does 
not  begin  with  a  dot. 

NAME  DOESN'T  MATCH 

Optional  name  given  in  .ENDM 
directive  does  not  match  name  given 
in  corresponding  .MACRO  directive. 

NESTED  MACROS 

A  macro  is  being  defined  or  invoked 
within  another  macro. 

NO  NAME 

A  macro  definition  has  no  name. 

SYNTAX 

A  macro  directive  is  not 

constructed  correctly. 

TOO  MANY  ARGS 

A  macro  directive  has  more  than  30 
arguments . 

CHAPTER  11 


ASEMBL ,  THE  8K  ASSEMBLER 

ASEMBL  is  designed  for  use  on  an  RT— 11  system  with  minimum  memory 
space  (or  larger  systems  where  system  table  space  is  critical)  and  is 
a  subset  of  the  RT-11  MACRO  assembler  described  in  Chapter  5.  ASEMBL 
has  the  same  features  as  MACRO  with  the  following  exceptions: 

1.  MACRO  directives  (.MACRO,  .MCALL,  .ENDM,  .IRP,  etc.)  are  not 
recognized 

2.  DATE  is  not  printed  in  listings 

3.  Wide  line-printer  output  is  not  available 

4.  There  is  no  lower-case  mode 

5.  There  is  no  enable/disable  punch  directive 

6.  There  are  no  floating  point  directives 

7.  There  are  no  local  symbols  or  local  symbol  blocks 

8.  CREF  is  not  available 

Many  of  the  macro  features  are  supported  by  the  EXPAND  program  (as 
described  in  Chapter  10). 

11.1  CALLING  AND  USING  ASEMBL 

ASEMBL  is  loaded  in  response  to  the  dot  printed  by  the  Keyboard 
Monitor  with  the  RT-11  monitor  R  Command  as  follows: 

R  ASEMBL 

followed  by  the  RETURN  key.  ASEMBL  responds  with  an  asterisk  (*)  and 
waits  for  specification  of  the  output  and  input  files  in  the  standard 
RT-11  format  as  follows : 

*object,listing=sourcel, . . . ,source6 
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where : 


object  is  a  binary  object  file  output  by  ASEMBL. 

listing  is  the  assembly  listing  file  containing  the 

assembly  listing  and  symbol  table. 

sourcel , . . . ,source6 

are  the  ASCII  source  files  containing  the  ASEMBL 
source  program(s).  A  maximum  of  six  source  files 
is  allowed. 

A  null  specification  in  any  of  the  file  fields  signifies  that  the 
associated  input  or  output  file  is  not  desired.  ASEMBL  file 
specifications  follow  the  standard  RT-11  convention  (devsfilnam.ext) . 
The  default  value  for  each  file  specification  is  noted  below: 


I/O  File 

Dev 

Ext 

object 

DK 

.OBJ 

listing 

device  used 
for  object  output 

•  LST 

sourcel , . . . , 

device  used  for 

.PAL 

sourcen 

last  source 
file  specified 
or  DK 

Type  CTRL  C  to  halt  ASEMBL  and  return  control  to  the  monitor.  To 
restart  ASEMBL,  type  R  ASEMBL  or  the  REENTER  command  in  response  to 
the  monitor's  dot. 

Table  11-1  lists  the  RT-11  macro  directives  which  are  not  available  in 
ASEMBL. 


Table  11-1 

Directives  not  Available  in  ASEMBL 


Directive 

Explanation 

.MACRO  ^ 

Macros  cannot  be  defined  in  ASEMBL. 

.ENDM  V 

.MEXIT  / 

.MCALL  J 

.NCHR 

The  number  of  characters  in  an  argument  cannot  be 

obtained  with  a  macro. 

.NARG 

The  number  of  arguments  in  a  macro  cannot  be 

obtained  with  a  macro. 

\  (backslash) 

Symbols  used  as  macro  arguments  cannot  be  passed 

as  a  numeric  string. 

(continued  on  next  page) 
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Table  11-1  (Cont.) 
Directives  not  Available  in  ASEMBL 


Directive 

Explanation 

.ERROR 

Messages  cannot  be  flagged  with  a  P  error  code 
output  as  part  of  the  assembly  listing.  Comment 
lines  can  be  used  to  replace  .ERROR. 

. IF  IDN  ^ 

.IF  DIF  J 

Strings  cannot  be  compared. 

•  IRP  \ 

• IRPC  J 

Indefinite  repeat  blocks  cannot  be  created. 

• NT YPE 

A  macro  cannot  be  modified  based  on  the  addressing 
mode  of  an  argument. 

.PRINT 

Messages  cannot  be  output  as  part  of  the  assembly 
listing.  Comment  lines  can  be  used  to  replace 
.PRINT. 

.REPT 

A  block  of  code  cannot  be  duplicated  a  number  of 
times  in-line  with  other  source  code  using  a 
directive. 

.LIST  ME 
.NLIST  ME 
.LIST  MEB 
.NLIST  MEB 
.LIST  MD 
.NLIST  MD 
.LIST  MC 
.NLIST  MC  * 

> 

These  directives  have  no  effect. 

.LIST  TTM  \ 

.NLIST  TTM  / 

Terminal  mode  is  standard  and  cannot  be  changed. 

. ENABL  LC  \ 

. DSABL  LC  J 

All  lower  case  ASCII  input  is  converted  to 
upper  case. 

.ENABL  LSB  \ 
.DSABL  LSB  / 

Local  symbols  and  local  symbol  blocks  are  not 
available  in  ASEMBL. 

.ENABLE  PNC  \ 
.DSABL  PNC  J 

Binary  output  is  always  enabled. 

.ENABL  FPT 
.DSABL  FPT 
.FLT2 
.FLT4 

} 

Floating  point  directives  are  not  available. 

Example : 

This  example  uses  the  output  produced  by  the  EXPAND  program  as  input 
to  ASEMBL.  The  assembly  listing  follows. 
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1  I  RT-il  MACRO  fcXPANO  V02-02 

2 
3 


4 

000001  R  1  *  X  1 

5 

000006  8P»X6 

6 

000007  PC*X7 

7 

1  .MACRO 

.CALL  . 

SUBR 

0 

I  J SR  PC, 

.  SU0R 

9 

1  .ENQM 

10 

1  • MC ALL 

.LOOKUP 

' .READ 

11 

I, MACRO  .LOOKUP 

.AREA. 

.CHAN..DEVBLK.. 

12 

l.lF  NOP  . . . V2 

13 

1 . IP  NB  .CHAN 

14 

1 

MOV 

. CM AN . X0 

IS 

I.ENDC 

10 

1 

EMT 

aO«20*,AREA> 

17 

f  .  iFP 

10 

I.IF  NB  .AREA 

19 

1 

MOV 

. area , xb 

20 

1 

MOV 

4400' (0) 

21 

1  ,E NOC 

22 

I.IF  NB  .CHAN 

23 

J 

MO  VB 

.CHAN, CO] 

24 

I.ENDC 

2S 

I.IF  NB  . OEvSLK 

26 

1 

MOV 

•DEVBLK , 2.(0) 

27 

I.ENDC 

26 

1 . IF  NB  . SPF 

29 

1 

MOV 

.SPF, 4. (0) 

30 

I.1PF 

31 

1 

CLR 

4.  (0) 

32 

i.endc 

33 

1 

EMT 

*0375 

34 

1,1 NOC 

35 

i.Endm 

36 

1. MACRO  .READ 

.AREA. 

.CHAN, .BUFF , .WC 

37 

1,17  NDF  .  • .  V2 

30 

I.IF  NB  . WCNT 

39 

1 

MOV 

• WCNT , X0 

40 

I.ENDC 

41 

I 

MOV 

41,-16.) 

42 

1 

MOV 

.BUFF , * (0. } 

43 

1 

MOV 

.CHAN, -(6.) 

44 

1 

EMT 

*O<200+, AREAF 

40 

1 ,177 

46 

1.  IP  NB  .AREA 

47 

1 

MOV 

.  AREA , X0 

40 

1 

MOV 

R4000, (0) 

49 

i.endc 

00 

I , IF  NB  .CHAN 

51 

1 

MOVB 

•  CHAN,  (0) 

02 

I.ENDC 

53 

I.1F  NB  • SLK 

54 

1 

MOV 

•  BLK ,2.  (0) 

55 

I.ENDC 

56 

1. IP  NB  .BUFF 

57 

1 

MOV 

•BUFF, 4. (0) 

BIK 
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.MAIN,  RT*ll  MACRO  V502«08  PaBE  1* 


58 

I.ENOC 

89 

I. IF  N8  * wCNT 

80 

I 

MOV 

•  WCnT ,6. (0) 

61 

l.tNDC 

62 

1 

MOV 

91.6. (0) 

63 

1 

EMT 

40375 

64 

I.ENOC 

63 

I.ENOM 

66 

000000' 

.CSECT 

MAIN 

67 

.8L0BL 

SORT 

68 

00000  STACKI 

« 8LKW 

100 

69 

00200  0UFRI 

•  BUKW 

100 

70 

00400  INBLKI 

.  BOAR 

10 

71 

00420  012706  START  1 

MOV  95TACK.8P 

000000* 

72 

00424  010146  A 1 

MOV  Rt 

# • CSP) 

73 

00426  gll 

.caul 

SORT 

74 

00426  004767 

JSR  PC 

.SORT 

000000G 

75 

> 

■LOOKUP  0.RIN0LK 

76 

.IF  NDF 

'  ...V2 

77 

.IF  NB 

•INBLK 

78 

00432  012700 

MOV 

9INBLK.X0 

000400) 

79 

,ENOC 

80 

00436  104020 

EMT 

*O<20+0» 

81 

.iff 

82 

.IF  NB 

0 

83 

MOV 

0.X0 

84 

MOV 

9400.  (0) 

85 

.ENOC 

86 

.IF  NB 

ftlNBLK 

87 

MO  VB 

9INBLK, (0) 

88 

.ENOC 

69 

.IF  NB 

90 

MOV 

.2. (0) 

91 

.ENOC 

92 

.IF  NB 

93 

MOV 

.4,(0) 

94 

.IFF 

95 

CLR 

4.(0) 

96 

.ENOC 

97 

EMT 

40375 

98 

.ENOC 

99 

00440  005001 

ClR  ri 

(BLOCK 

NUMBER 

100 

r 

.READ  0 . 9BUFR • 

#256, ,Rl 

101 

.IF  NOF 

...V2 

102 

.IF  NB 

Rl 

103 

0442  010100 

MOV 

R1.X0 

104 

.ENOC 

105 

0444  012746 

MOV 

91 ,■  (6, ) 

000001 

106 

0450  012746 

MOV 

9236, ,-(6.) 

000400 

107 

0454  012746 

MOV 

9BUFR. • (6, ) 

000200 

108 

0460  104200 

EMT 

404200*09 
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109 

.1^ 

110 

,IP  NB 

0 

111 

MOV 

0,X0 

112 

MOV 

R4000,  (0) 

113 

.ENOC 

1 1 A 

.IF  NB 

*B(JF  R 

115 

MOVB 

*BUP«, C0) 

115 

.ENOC 

117 

.IP  NB 

110 

MOV 

,2.(0) 

119 

,ENDC 

120 

.IP  nb 

*256 , 

121 

MOV 

*256, ,4. ( 

122 

.ENOC 

123 

.IP  NB 

R 1 

124 

MOV 

Ml, 6. (8) 

125 

.ENOC 

120 

MOV 

«1,8*  (0) 

127 

EMT 

*0375 

120 

.ENOC 

129  0462 

000000 

halt 

130 

000420 

i 

.ENO 

START 

.MAIN,  K T • 1 1  MACRO  VS02-OB  PAGE  1  + 
SYMBOL  TABLE 


A 

000424R 

002 

JNBLK 

000400R 

002 

SP 

•X000006 

start 

000420R 

002 

.  ABS 

,  000000 

000 

000000 

001 

MAIN 

000464 

002 

errors  oetecteos 

0 

FREE 

CORE  1  19117 

.  WORDS 

B  000426R  002 

PC  *X000007 
SQR T  *  ******  G 


BUFR 

000200R 

002 

R1 

•X00B001 

STACK 

000000R 

002 

,lm**chh,pal 
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The  system  error  messages  output  for  ASEMBL  are  abbreviated  as 
follows : 


Abbreviation 


Explanation 


?BSW?  The  switch  specified  was  not  recognized  by  the 

program. 

7CORE?  There  are  too  many  symbols  in  the  program  being 

assembled.  Try  dividing  program  into  separately 
assembled  subprograms. 


?NIF?  No  input  file  was  specified  and  there  must  be  at 

least  one  input  file. 

?ODF?  No  room  to  continue  writing  output;  try  to 

compress  device  with  PIP. 


?TMO? 


Too  many  output  files  were  specified. 
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ASSEMBLY ,  LINK,  AND  BUILD  INSTRUCTIONS 


This  appendix  describes: 

1.  The  system  building  procedure  from  each  of  the  possible 
distribution  media 

2.  Customization  of  the  system  for  special  hardware  (LA30's, 
VT05B,  7-Track  Magtape,  varying  numbers  of  RF11  platters, 
50-cycle  clock  rates) 

3.  Optimizations  which  can  be  affected  at  system  build  time 

4.  Assembly  and  linking  instructions  for  system  components 


NOTE 

This  appendix  assumes  the  user  has  read 
and  is  familiar  with  the  entire  RT-11 
SYSTEM  REFERENCE  MANUAL,  especially 
Chapter  2  (System  Communication) ,  Chapter 
4  (PIP) ,  and  Chapter  6  (LINK) .  For 
step-by-step  instructions  for  building  the 
system  the  first  time,  refer  to  GETTING 
STARTED  WITH  RT-11  (DEC-11-0RCPA-D-D) . 


A.l  BUILDING  RT-11  SYSTEMS 

RT-11  is  designed  so  that  the  monitor  and  device  handlers  which 
comprise  the  system  are  files  on  the  system  device.  These  files 
(called  system  files)  all  have  the  extension  ".SYS",  and  can  be 
manipulated  between  devices  just  like  any  other  RT-11  file. 

The  running  version  of  the  monitor  must  be  named  MONITR.SYS;  other 
versions  of  the  monitor  may  reside  on  the  system  device,  but  they  must 
be  named  something  other  them  MONITR.SYS.  The  hemdlers  for  the  system 
must  be  named  xx.SYS,  where  xx  is  the  device  mnemonic  as  used  in 
command  strings.  For  example ,  the  high-speed  reader  hemdler  must  be 
neuned  PR. SYS.  There  may  be  many  versions  of  a  given  handler  on  the 
system  device,  but  the  one  that  is  in  use  must  be  named  as  above. 
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Once  copies  of  the  system  files  have  been  obtained,  the  procedure  for 
building  an  RT-11  system  consists  of  the  following  basic  steps: 

1.  initializing  the  target  device  with  an  RT-11  directory 

2.  Transferring  the  appropriate  monitor  file  to  the  target 
device  and  giving  it  the  name  MONITR.SYS 

3.  Transferring  the  appropriate  handler  files  to  the  target 
device 

4.  Writing  the  appropriate  bootstrap  on  the  target  device 

5.  Transferring  the  rest  of  the  system  components  (EDIT,  LINK, 
etc.)  to  the  target  device 

After  step  4  above,  the  target  device  may  be  bootstrapped  and  the 
remainder  of  the  build  procedure  may  be  carried  out  while  executing 
the  system  from  the  new  (and  perhaps  faster)  system  device.  Because 
the  above  build  steps  involve  standard  RT-11  file  operations,  system 
programs  are  used  for  the  build  procedure.  When  building  from 
DECtape,  PIP  is  used;  from  cassette,  CBUILD  is  used;  and  from  paper 
tape,  LINK  and  PIP  are  used.  RT-11  V02  can  be  bootstrapped 

write— protected,  and  will  run  PIP  write— protected  as  well.  System 
building  should  always  be  carried  out  with  the  master  write-protected. 


A.  1.2  DECtape  from  DECtape  or  Disk,  and  Disk  from  DECtape  or  Disk 

On  DECtape  or  DECpack  disk,  RT-11  is  distributed  as  a  "ready-to-run" 
Single-Job  system.  When  bootstrapped  (as  described  in  Chapter  2) ,  the 
system  is  running  and  may  be  used  to  build  other  DECtape  and  disk 
systems.  The  following  files  on  the  distributed  system  DECtape  or 
disk  have  special  significance  (all  are  not  present  on  all  media) : 

MONITR.SYS  On  a  DECtape  master  this  is  a  Single- Job 

DECtape  Monitor;  on  a  DECpack  disk  master 
and  a  TAll  cassette  master  this  is  a 
Single-Job  RK-11  Disk  Monitor.  When  the 
volume  is  booted,  this  file  is  the  monitor 
used. 


DTMNS J.SYS 


DTMNFB.SYS 


RKMNS J.SYS 


This  is  a  Single- Job  DECtape  Monitor,  used 
for  building  DECtape-based  Single-Job  systems 
(not  available  on  paper  tape  or  cassette) . 

This  is  a  Foreground/Background  DECtape 
Monitor,  and  is  used  when  it  is  desired  to 
run  the  F/B  system  from  DECtape  (not 
available  on  paper  tape  or  cassette) . 

This  is  a  Single- Job  RKll  Monitor.  When 
building  a  Single- Job  disk  system,  this  file 
becomes  MONITR.SYS  on  the  disk. 


RKMNFB.SYS  This  is  a  Foreground/Background  RKll  Monitor. 

If  an  RKll  F/B  system  is  desired,  this  file 
becomes  MONITR.SYS  on  the  disk. 
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RFMNFB.SYS 


RFMNFB.SYS 


RF.SYS 


RK.SYS 


DT.SYS 


CR.SYS 
MT.SYS 
CT.SYS 
PR. SYS 

PP.SYS 

TT.SYS 

LP.SYS 


This  is  a  Single-Job  RF11  Monitor, 
corresponding  to  RKMNSJ.SYS  (not  available  on 
cassette) . 

This  is  a  Foreground/Background  RF11  Monitor, 
corresponding  to  RKMNFB.SYS  (not  available  on 
cassette) • 

This  file  is  an  RF11/RS11  device  handler, 
which  allows  RT-11  systems  running  from 
DECtape  or  DECpack  disks  to  access  the  RF11 
disk  (not  available  on  cassette) . 

This  is  an  RK11  device  handler,  which  allows 
RT-11  to  read  and  write  RK11  disks  while 
running  a  DECtape  or  RF11  system. 

This  is  a  TC11  DECtape  handler,  which  allows 
RT— 11  to  read  and  write  DECtape  while  running 
disk  systems  (not  available  on  DECtape  or 
cassette) . 

This  is  the  card  reader  handler  (CR11,  CM11) . 

This  is  the  magtape  handler  (TM11/TU10). 

This  file  is  the  cassette  (TA11)  handler. 

This  is  the  high-speed  reader  (PC-11) 
handler. 

This  is  the  high-speed  punch  (PC-11)  handler. 

This  is  the  general  terminal  handler. 

This  is  the  line  printer  (LP-11,  LS-11, 

LV— 11)  handler. 


To  build  another  DECtape  or  DECpack  system  (on  unit  n)  from  a  running 
DECtape  or  DECpack  system,  the  following  set  of  commands  to  PIP  can  be 
used  (commands  illustrated  in  this  appendix  are  terminated  with  the 
carriage  return  key) . 

Commands  Explanation 

.R  PIP 

*DKn:/Z  Initialize  the  new  DECtape  or  Disk. 

DKn/Z  ARE  YOU  SURE7Y 

*DKnsA»DK0 :/S  Copy  all  files  from  DKO  to  DKn. 

*DKn:A=DKn:MONITR.SYS/U  Write  the  hardware  bootstrap  on  DKn. 

Unit  n  now  is  a  ready-to-run  copy  of  the  system  DECtape  or  Disk. 

In  the  above,  the  system  files  were  copied  to  DK:  via  the  /S  option 
in  PIP;  in  actuality,  any  method  of  copying  the  files  to  the  new 
device  would  have  sufficed.  For  example,  the  command: 

*DKn :  A**DK0 :  /S 
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could  have  been  replaced  bys 

*DKn : * . *=DK0  s  * . *  A/X 
or 

*DKn  sMONITR. SYS=MONITR. SYS A 
*DKn : LP . SYS-LP . SYS A 


etc.,  until  all  desired  files  were  transferred. 

To  build  an  RK11  disk  system  from  a  running  DECtape  system,  use  the 
following  commands: 


Commands 


Explanation 


.R  PIP 
*RK  s /Z 

RK:/Z  ARE  YOU  SURE7Y 
*RK:A=DT0:/S 

*RK :  DTMNSJ  .  SYS=RK  sMONITR.  SYS/Y/R 


*  RK :  MONITR.  SYS»RK :  RKMNSJ  .  SYS  A/R 


*RK:A=RK sMONITR. SYS/U 


Initialize  the  disk. 

Copy  the  DECtape  files  onto 
disk. 

Rename  the  DECtape  monitor  on 
the  disk  to  an  appropriate 
name. 

Rename  the  disk  monitor  on  the 
disk  to  MONITR. SYS  (in  this 
case,  the  Single- Job  Monitor). 
Write  the  system  bootstrap  on 
the  disk. 


The  RKll  disk  may  now  be  bootstrapped  as  described  in  Chapter  2,  or 
with  the  PIP  /0  option.  The  original  DECtape  MONITR. SYS  file  must  be 
renamed  to  another  name  before  the  RK  monitor  is  named  to  MONITR. SYS, 
or  it  will  be  automatically  deleted  when  the  RK  monitor  rename  is 
performed. 

To  build  an  RFll  disk  system  from  a  running  disk  or  DECtape  system, 
use  the  following  commands: 


Commands 


.R  PIP 
*RF • /Z 

RFs/Z  ARE  YOU  SURE  ?Y 
*RF:*.*=SYs*.  *AA 


*RF:  XXMNYY  .  SYS=RF  s  MONITR.  SYS  A/R 


*RF  sMONITR.  SYS=RF  s  RFMNFB  .  SYS  A/R 


*RF  sA=RF  sMONITR. SYS/U 


Explanation 

Initialize  the  disk. 

Copy  all  files  from  the 
running  system  to  the  new 
system. 

Rename  the  DECtape  or  RK 
monitor  on  the  RF  to  an 
appropriate  name. 

Rename  the  desired  RF  monitor 
on  the  RF  disk  to  MONITR. SYS 
(in  this  case  the  F/B 
Monitor) . 

Write  the  system  bootstrap  on 
the  RF  disk. 
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The  RF11  disk  may  now  be  bootstrapped  as  described  in  Chapter  2,  or 
with  the  PIP  /0  option. 

Note  that  in  the  above  examples,  all  files  were  copied  from  the 
running  system  to  the  system  being  built.  Although  this  is  a  common 
practice,  it  is  not  necessary,  and  is  usually  not  possible  when  the 
running  system  is  disk  and  the  target  device  is  DECtape.  The 
requirement  is  that  the  following  elements  be  transf erred s 

1.  A  monitor  file 

2.  The  handlers  for  the  desired  devices 

3.  The  hardware  bootstrap 

4.  Those  programs  and  files  which  will  be  used  with  the  new 
system 

When  building  a  system  for  a  configuration  which  contains  only  LA30 
and  DECtape,  it  is  wise  to  avoid  transferring  any  of  the  unrequired 
handler  files  (DT  is  the  system  handler  in  the  monitor)  as  they 
require  space  on  the  system  DECtape,  yet  serve  no  purpose.  Users  of 
8K  machines  may  choose  to  build  systems  without  the  file  MACRO. SAV, 
while  EXPAND. SAV  and  ASEMBL.SAV  can  be  eliminated  from  systems  with 
16K  or  more  of  memory.  The  system  is  distributed  with  six  monitor 
files,  yet  the  system  only  requires  one  for  day-to-day  operation,  and 
seldom  would  an  application  have  a  need  for  more  than  two  (the  Single 
Job  and  Foreground/Background  monitors  often  reside  on  the  same  volume 
for  convenient  switching) . 


A. 1.3  Switching  Between  Single- Job  and  Foreground/Background 

For  an  application  that  requires  frequent  switching  between  the  F/B 
and  Single- job  monitors,  the  following  procedure  is  followed: 

1.  Both  monitors  reside  on  the  same  volume,  the  one  running 
named  MONITR.SYS  and  the  other  called  XXXXXX.SYS.  (The 
actual  name  XXXXXX  is  not  significant.) 

2.  When  a  change-over  is  desired,  PIP  is  used  to: 

a.  Preserve  the  running  monitor  by  renaming  it  to  YYYYYY . SYS 

b.  Rename  the  desired  monitor  to  MONITR.SYS 

c.  Write  the  new  bootstrap  from  the  new  MONITR.SYS  file 

d.  Reboot  the  system 

For  example,  assume  an  RK11  system  is  running  the  Single- Job  Monitor, 
with  the  Foreground/Background  Monitor  present  as  the  file  RKMNFB.SYS • 

.R  PIP 

*rkmnsj.sys=monitr.sys/y/R 

? REBOOT? 

*MONITR. SYS=RKMNFB . SYS/Y/R 
7REB00T? 


Write  the  new  bootstrap. 
Reboot  the  system. 
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Activate  the  F/B  Monitor  by 
renaming  it  to  MONITR.SYS. 
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A.  1.4  Disk  from  Cassette 

On  cassette,  RT-11  is  distributed  as  a  series  of  RT-11  files  on 
several  cassettes,  each  cassette  labeled  DEC-ll-ORTSA-C-TCn.  The 
following  files  on  the  system  cassettes  have  special  significance: 

CBUILD. SYS  CBUILD  is  the  special  system-build  version  of 

PIP  which  is  loaded  via  the  cassette 
bootstrap.  This  program  is  used  to 
initialize  the  disk  and  transfer  the 
remaining  files  from  cassette  to  disk. 
CBUILD. SYS  is  used  to  build  RK11  systems 
only. 

MONITR.SYS  The  RT-11  Single- Job  RK11  Monitor  file. 

The  remaining  .SYS  files  are  the  monitor  and  handler  files  as 
described  for  the  DECpack  disk  and  DECtape  systems  in  A.1.2. 

To  build  an  RT-11  system  from  cassette,  perform  the  following 
operations : 

1.  Mount  an  RT-11  cassette  which  has  the  file  CBUILD. SYS  as  its 

first  file  on  Unit  0. 

2.  Bootstrap  cassette  Unit  0  as  follows: 

Load  and  start  the  system  bootstrap  loader  (called  CBOOT) . 

This  can  be  done  in  one  of  two  ways: 

a.  If  the  system  has  a  hardware  cassette  bootstrap,  enter 
173300  in  the  Switch  Register,  press  LOAD  ADDR  and  START. 
(Step  b  may  be  ignored.) 

b.  If  no  hardware  bootstrap  is  available,  CBOOT  must  be 
manually  loaded  and  started  by  the  user.  Two  versions  of 
CBOOT  are  provided.  The  standard  version  is  the  version 
used  in  the  hardware  bootstrap  and  consists  of  the  28 
words  listed  in  Table  A-l. 

A  shorter  (20-word)  version  called  QCBOOT  may  optionally 
be  loaded  by  the  user.  This  version  does  not  provide 
some  of  the  error  checking  and  handling  which  the  longer 
CBOOT  does,  but  allows  a  faster  means  of  manually  booting 
the  system.  The  binary  instructions  are  also  listed  in 
Table  A-l: 
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Table  A-l 

CBOOT  (QCBOOT)  Instructions 


Location 

CBOOT 

QCBOOT 

Contents 

Contents 

001000 

012700 

012700 

001002 

177500 

177500 

001004 

005010 

005010 

001006 

010701 

010701 

001010 

062701 

062701 

001012 

000052 

000034 

001014 

012702 

112102 

001016 

000375 

112110 

001020 

112103 

032710 

001022 

112110 

100240 

001024 

100413 

001775 

001026 

130310 

100001 

001030 

001776 

005007 

001032 

105202 

005202 

001034 

100772 

100770 

001036 

116012 

116012 

001040 

000002 

000002 

001042 

120337 

000766 

001044 

000000 

017775 

001046 

001767 

002415 

001050 

000000 

001052 

000755 

001054 

005710 

001056 

100774 

001060 

005007 

001062 

017640 

001064 

002415 

001066 

112024 

After  the  bootstrap  has  been  manually  loaded  (using  the 
Switch  Register,  LOAD  ADDR,  and  DEP  keys) ,  set  001000  in  the 
switches,  press  LOAD  ADDR  and  START.  At  this  point  the  RUN 
lamp  should  be  lit  and  the  system  cassette  should  begin  to 
move. 


3.  CBUILD  will  print  the  following  on  the  console  terminal. 

CBUILD  Version  number 
* 


CBUILD  is  a  stand-alone  version  of  PIP.  Use  the  following 
set  of  commands  (or  their  equivalent)  to  build  the  disk 
system. 


Commands 


Explanation 


*RK:/Z 

RKx/Z  ARE  YOU  SURE  ?Y 


*RK : * . *=CTn : * . */Y/X 


Initialize  disk  directory. 


Write  system  files  on  disk. 
Repeat  this  command  for  each 
cassette  necessary  to  build  the 
desired  system. 
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*RK:A=CTn:MONITR.SYS/U  Write  bootstrap  on  disk. 

*RK:/0  Boot  the  disk  system. 

RT-11  is  then  running  from  the  disk  and  may  be  used  in  the  normal 
fashion  to  copy  any  other  desired  files  from  cassette  to  disk.  Note 
that  no  devices  other  than  disk  or  cassette  can  be  used  until  their 
handler  files  have  been  added  to  the  disk  and  the  system  has  been 
rebooted. 


A. 1.5  Disk  from  Paper  Tape 


RT-11  is  distributed  as  object  modules  on  paper  tape.  Two  of  the 
tapes  (PT  BUILD  Tape  1  and  2)  are  used  to  place  a  rudimentary  V01-15 
monitor  and  Linker  on  the  disk.  The  disk  system  is  then  started  and 
the  Linker  is  used  to  link  OLDPIP  from  paper  tape  onto  the  disk.  Once 
linked,  OLDPIP  is  used  to  copy  the  remaining  paper  tapes  onto  the  disk, 
where  they  can  be  linked  to  complete  the  system. 


The  following  RT-11  paper  tapes  have  special  significance; 

DEC-11— ORPBA-C-PBl I  This  paper  tape  is  for  RK11  systems  only. 
RK  PT  BUILD  Tape  lj 

DEC-11-0RPBA-C-PB2 )  This  paper  tape  is  for  both  RK11  and  RF11 
PT  BUILD  Tape  2  i  systems. 

DEC- 11-ORPBA— C— PB 3  I  This  paper  tape  is  for  RF11  systems  only. 

RF  PT  BUILD  Tape  If 

To  build  an  RT-11  system  from  paper  tape,  perform  the  following 
operations : 

1.  Load  the  Bootstrap  Loader  at  37744,  then  use  it  to  load  the 
Absolute  Loader. 

2.  Using  the  Absolute  Loader,  load  the  appropriate  PT  BUILD  Tape 
1  for  the  system  device  desired.  It  self-starts  and  prints; 

PT  BUILD  Version  number 

3.  There  is  a  10-15  second  pause,  after  which  PT  BUILD  prints: 

PLACE  SECOND  TAPE  IN  READER. 

STRIKE  ANY  CHARACTER  TO  CONTINUE. 


4.  Place  the  tape  PT  BUILD  Tape  2  into  the  reader,  then  strike 
any  character  to  start  the  tape. 

There  is  a  slight  pause,  after  which  the  following  is 
printed. 

DISK  BUILD  COMPLETE.  [A  rudimentary  VO 1-15  monitor 

is  used  to  build  the  VO 2 
RT-11  V01-15  system.] 
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During  the  build  procedure,  only  a 
WRITE  FAILED 

error  message  has  exact  meaning.  If  encountered,  check  to 
make  sure  the  system  disk  is  not  write  protected.  Any  other 
error  indicates  a  hardware  or  disk  problem. 

5.  Link  OLDPIP  as  follows: 

.R  LINK 

*OLDPIP=PR: 

ft* 

For  each  occurrence  of  the  prompting  "t",  place  the  tape 
OLDPIP.OBJ  (DEC-11-0R0PA-C-PR)  in  the  reader,  then  strike  a 
character  to  read  the  tape.  Type  CTRL  C  when  the  second 
is  printed. 

6.  Run  OLDPIP  to  copy  the  remaining  tapes  on  the  system  disk 
(use  the  /B  switch  for  all  files  but  SYSMAC.SML,  SYSMAC.8K, 
and  VTMAC.MAC,  which  require  /A) .  Unlike  the  VO 2  system  when 
built,  OLDPIP  prompts  with  am  up-arrow  or  circumflex  prior  to 
reading  each  tape,  and  proceeds  when  a  character  is  struck  at 
the  keyboard.  For  example: 


COMMAND 


USE  TAPE 


.R  OLDPIP 

*  PATCH . OB J=PR : /B 

t*PIP.OBJ=PR:/B 

t*ODT.OBJ=PR:/B 

t  *  PREXEC . OB J«PR : /B 

t*PREPAS.OBJ=PR:/B 

t  *SMEXEC . OB J=PR : /B 

t  *SMMAC . OB J=PR : /B 

t*SMPST.OBJ=PR:/B 

t  *  RTEXEC . OB J=PR : /B 

t*RTMAC . OB J=PR : /B 

t*RTPST.OBJ»PR:/B 

t  *S YSMAC . SML=PR :  /A 

t*SYSMAC. 8K=PR:/A 

t  *' VTMAC . MAC=PR : /A 

t  * VTHDLR. OB J=PR : /B 

t*CT.OBJ=PR:/B 

t*MT.OBJ=PR:/B 

t*CR.OBJ=PR:/B 

t*PP.OBJ«PR:/B 

t*PR.OBJ=PR:/B 

t*LP.OBJ=PR:/B 

t*TT.OBJ=PR:/B 

t*RF.OBJ«PR:/B 

t*RK.OBJ=PR:/B 

t  *  RFBTFB . OB J=PR : /B 

t  *  RKBTFB . OB J»PR : /B 

t  *  RFBTSJ . OB J»PR : /B 

t*RKBTSJ.OBJ=PR:/B 

t  *RT1 1FB . OB J«PR : /B 

t  *RT1 IS J . OB J=PR : /B 


(PATCH. OBJ 

(PIP. OBJ 

(ODT.OBJ 

(PREXEC. OBJ 

(PREPAS .OBJ 

(SMEXEC.OBJ 

(SMMAC.OBJ 

(SMPST.OBJ 

(RTEXEC. OBJ 

(RTMAC.OBJ 

(RTPST.OBJ 

(SYSMAC.SML 

(SYSMAC.8K 

(VTMAC.MAC 

(VTHDLR. OBJ 

(CT.OBJ 

(MT.OBJ 

(CR.OBJ 

(PP.OBJ 

(PR. OBJ 

(LP.OBJ 

(TT.OBJ 

(RF.OBJ 

(RK.OBJ 

(RFBTFB. OBJ 

(RKBTFB. OBJ 

(RFBTSJ. OBJ 

( RKBTS J . OBJ 

(RT11FB.0BJ 

(RT11SJ.OBJ 


DEC— 11— ORPAA— C— PR) 
DEC— 11— ORPPA— C— PR) 
DEC-1 1— ORODA— C— PR) 
DEC— 11-ORE XA-C-PRl) 
DEC-11-OREXA-C-PR2 ) 
DEC— 11— ORTAA— C— PRl) 
DEC-11-0RTAA-C-PR2 ) 
DEC— 11-ORTAA-C-PR3) 
DEC-1 1-ORMAA-C-PR1 ) 
DEC-1 1-ORMAA-C-PR2 ) 
DEC- 1 1-0RMAA-C-PR3  ) 
DEC-1 1-ORSYA— C— PA1 ) 
DEC-1 1-ORSYA— C-PA2 ) 
DEC— 11— OVTMA— C— PA) 
DEC— 1 1— OVTH A— C— PR) 
DEC— 11— OCAHA— C— PR) 
DEC— 11-OMTHA— C— PR) 
DEC— 11— OCRHA— C— PR) 
DEC— 11— ORTPA— C— PR) 
DEC— 1 1— ORPHA— C— PR) 
DEC-1 1-ORTLA-C-PR) 
DEC-1 1-ORTTA-C-PR) 
DEC— 11— ORFHA— C— PR) 
DEC— 1 1— ORKHA— C— PR) 
DEC-1 1-0RBTA-C-PR1 ) 
DEC-1 1— ORBTA— C— PR2 ) 
DEC-11-ORBTA-C-PR3 ) 
DEC-1 1— ORBTA— C—PR4 ) 
DEC-1 1-ORMNA-C-PR1 ) 
DEC-1 1-ORMNA-C-PR2 ) 
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t*EDIT.OBJ=PR:/B 
t*VTCED1.0BJ=PRs/B 
t * VTCED4 . OB J-PR * /B 
t  * VTBEDT . OB J»PR : /B 
t*LINKO.OBJ=PR:/B 
t  *LNKOVl . OB J=PR : /B 
t*LNKOV2 ,OBJ=PR:/B 
t  *LNKOV3 . OB J-PR  s /B 
t  *LNKOV4 . OB J=PR  s /B 
t  *LNKOV5 . OB J=PR  s /B 
t * DUMP . OB J-PR : /B 
t *SRCCOM. OB J-PR  s /B 
t  *FILEX . OB J-PR : /B 
t*LIBR0 .OBJ-PR:/B 
t*LIBR1.0BJ=PR:/B 
t  *LIBR2 . OB J-PR: /B 
t*LIBR3.0BJ»PR:/B 
t  *LIBR4 . OB J-PR  s /B 
t*CREF.OBJ«PRs/B 
t*PATO.OBJ-PR:/B 
t*PAT1.0BJ-PR:/B 
t*PAT2.0BJ=PR:/B 
t*PAT3.0BJ-PR:/B 
t*PAT4.0BJ=PR:/B 
t*PAT5.0BJ-PR:/B 
t*PAT6.0BJ-PR:/B 
t*IRAD50 .OBJ=PR:/B 
t  *  R50 ASC . OB J-PR : /B 


(EDIT. OBJ 

(VTCEDl.OBJ 

(VTCED4.0BJ 

(VTBEDT.OBJ 

(LINKO.OBJ 

( LNKOV1 . OBJ 

(LNK0V2.0BJ 

(LNK0V3.0BJ 

(LNK0V4.0BJ 

(LNK0V5.0BJ 

(DUMP. OBJ 

(SRCCOM.OBJ 

(FILEX.OBJ 

(LIBRO.OBJ 

(LIBRl.OBJ 

(LIBR2.0BJ 

(LIBR3.0BJ 

(LIBR4.0BJ 

(CREF.OBJ 

(PATO.OBJ 

(PATl.OBJ 

(PAT2.0BJ 

(PAT3.0BJ 

(PAT4.0BJ 

(PAT5.0BJ 

(PAT6.0BJ 

(IRAD50.OBJ 

(R50ASC.OBJ 


DEC-11-ORTEA-OPR1) 
DEC-1 1-ORTEA-C-PR2) 
DEC-1 1-ORTEA-C-PR3 ) 
DEC- 1 1-ORTEA— C-PR4 ) 
DEC-1 1-ORLLA-C-PR1 ) 
DEC-1 1-ORLLA-C-PR2 ) 
DEC-1 1-ORLLA-C-PR3) 
DEC- 1 1-ORLLA-C-PR4 ) 
DEC- 1 1-ORLLA-C-PR5 ) 
DEC-11-ORLLA-C-PR6 ) 
DEC— 11-ORDMA-C— PR) 
DEC— 11— OS RCA— C— PR) 
DEC— 11— ORFLA-C— PR) 
DEC— 1 1— ORLB A— C— PRl ) 
DEC-11-ORLBA-C-PR2) 
DEC-11-ORLBA-C-PR3 ) 
DEC-11-ORLBA-C-PR4 ) 
DEC- 1 1-ORLB A-C-PR5 ) 
DEC— 11— ORCFA— C— PR) 
DEC-1 1-ORPOA-C-PR1 ) 
DEC— 11-ORPOA— C— PR2) 
DEC— 11-ORPOA— C— PR3) 
DEC-1 1-ORPOA-C-PR4) 
DEC- 1 1— ORPOA— C— PR5 ) 
DEC-1 1-ORPOA-C-PR6 ) 
DEC— 11— ORPOA— C—PR7 ) 
DEC— 11— ORPOA— C—PR8 ) 
DEC-1 1-ORPOA-C-PR9 ) 


PREXEC.OBJ  and  PREPAS.OBJ  are  the  object  modules  for  EXPAND. 
SMEXEC  *  OBJ ,  SMMAC.OBJ  and  SMPST.OBJ  are  linked  for  ASEMBL, 
while  RTEXEC . OBJ ,  RTMAC.OBJ  and  RTPST.OBJ  are  the  MACRO 
object  modules.  PIP. OBJ  is  the  object  module  for  PIP. 

VTHDLR,  after  a  pass  by  the  Librarian,  becomes  the  display 
handler.  CT.OBJ  through  RK.OBJ  are  linked  into  handlers  of 
the  same  name;  RFBTFB.OBJ  through  RT11SJ  are  the  RF11  and 
RK11  monitor  components.  EDIT. OBJ  and  VTLEDT.OBJ  make  the 
editor,  while  LINKO  through  LNKOV5  are  the  components  for  the 
VO 2  Linker.  DUMP. OBJ,  SRCCOM.OBJ,  FILEX.OBJ,  and  CREF.OBJ 
are  linked  for  programs  of  the  same  name,  while  LIBRO  through 
LIBR4  become  the  Librarian.  PATO  through  R50ASC  are  linked 
with  RT-11  FORTRAN  (if  available)  to  make  PATCHO. 

If  a  specific  component  is  not  required,  it  is  not  necessary 
to  transfer  the  corresponding  tapes. 

7.  Run  LINK  to  generate  the  V02  .SYS  files  and  program  .SAV 
files  as  described  later  in  this  appendix  (Section  A. 4. 2). 
Linking  the  new  VO 2  Linker  will  generate  ADDITIVE  REF 
messages,  which  should  be  ignored.  Once  the  V02  Linker  is 
built,  it  should  be  used  for  subsequent  linking  operations. 

8.  Reboot  the  system  (with  PIP  if  desired) .  The  .OBJ  files 
(except  for  ODT  and  VTLIB)  can  be  deleted  as  well  as 
OLDPIP.SAV,  as  they  are  no  longer  required. 
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A, 2  CUSTOMIZATION  FOR  SPECIAL  HARDWARE 


A. 2.1  High  Baud  Rate  Serial  Console  Devices 

The  serial  LA30  requires  that  filler  characters  follow  each  carriage 
return;  the  600,  1200  and  2400  baud  VT05's  require  that  filler 

characters  follow  each  line  feed.  RT-11  has  established  a  mechanism 
by  which  any  number  of  fills  may  follow  any  character.  The  byte  at 
location  56(8)  contains  the  character  to  be  followed  by  fillers  and 
the  byte  at  location  57(8)  contains  the  number  of  null  fills  to  be 
used.  These  locations  are  initially  set  to  zero  which  results  in  no 
fillers  being  generated  (normal  operation  for  LT33  and  LA30P) . 

Depending  on  the  terminal,  modify  the  locations  as  follows: 


Loc  56 

Loc  57 

Resulting  Word  (octal) 

LA30s  110  baud 

015(8) 

002(8) 

1015 

LA30s  150  baud 

015(8) 

004(8) 

2015 

LA30s  300  baud 

015(8) 

012(8) 

5015 

VT05  600  baud 

012(8) 

001(8) 

412 

VT05  1200  baud 

012(8) 

002(8) 

1012 

VT05  2400  baud 

012(8) 

004(8) 

2012 

The  proper  octal  word  can  be  changed  permanently  in  the  monitor  by 
using  PATCH  to  modify  locations  56  and  57  in  the  monitor  file.  For 
example : 

Commands  Explanation 

.R  PATCH 

PATCH  Version  number 

FILE  NAME-- 
*MONITR. SYS/M 

*56\0  15<LF>  Fill  after  CR 

*57\0  4  with  4  nulls. 

*E 


Once  the  change  has  been  made  and  the  bootstrap  has  been  rewritten 
with  the  PIP  /U  switch,  all  programs  which  use  the  monitor  for  console 
I/O  will  operate  correctly. 


A.  2 . 2  7-Track  Magtape 

The  RT-11  magtape  handler  is  distributed  such  that  it  will  correctly 
handle  both  7-  and  9- track  magtape  without  modification.  It  does  so 
at  800  BPI,  using  the  TM11  dump  mode  for  7-track  drives.  7-track 
drives  can  also  be  written  (in  hardware  mode  only;  See  Appendix  H)  at 
200,  556  and  800  BPI  (non-dump  mode)  by  modifying  the  handler  as 
described  below. 

The  density  value  is  located  at  1104(8)  in  the  magtape  handler,  and 
can  be  modified  with  PATCH.  To  alter  the  magtape  density  used  by  the 
handler,  simply  modify  location  1104(8)  to  the  appropriate  value  from 
the  table  below.  Note  that  the  density  of  9-track  tapes  cannot  be 
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altered.  Note  also  that  all  drives  are  written  in  the  same  density; 
if  different  drives  of  different  densities  are  to  be  used  on  the  same 
machine,  different  handlers  must  be  used  for  each. 

Density  Value  of  1104(8) 


200  BPI,  7-TRK  000000 
556  BPI,  7-TRK  020000 
800  BPI,  7-TRK  040000 
800  BPI-DUMP  MODE 

7-TRK  060000 
800  BPI,  9-TRK  060000 


For  example,  to  cause  RT-11  to  write  7-track  tapes  at  556  BPIs 


.R  PATCH 

PATCH  Version  number 

FILE  NAME — 

*MT.SYS 

*1104/60000  20000 
*E 


A. 2.3  Specifying  the  Number  of  RF11  Platters 

RF-11  is  distributed  with  RF11  support  initialized  for  one  RF11 
platter.  To  allow  RT-11  to  make  use  of  more  than  one  platter,  the 
device  size  table  in  the  various  monitor  files  must  be  modified  as  fol¬ 
lows  : 


New  Value  of  Table  Number  of  Platters 


2000 

1 

4000 

2 

6000 

3 

10000 

4 

Monitor 

Table  Addr< 

RKMNSJ 

30702 

RKMNFB 

32602 

DTMNSJ 

30702 

DTMNFB 

32602 

RFMNSJ 

30702 

RFMNFB 

32602 

For  example,  to  modify  the  RF11  F/B  Monitor  for  3  RF/RS11  platters, 
type: 


.R  PATCH 

PATCH  Version  number 

FILE  NAME— 

*RFMNFB. SYS/M 
*32602/2000  6000 
*E 
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Once  the  above  change  has  been  made,  zeroing  (PIP  /Z  switch)  the  RF 
disk  will  adjust  the  directory  to  the  appropriate  size.  If  the  system 
is  already  running  off  RF11  as  the  system  device  and  the  disk  cannot 
be  zeroed  without  destroying  the  system,  compressing  the  disk  (with 
the  PIP  /S  switch  )  will  automatically  re-adjust  the  directory  size. 


A. 2. 4  Specifying  a  50-cycle  Clock  Rate 

RT-11  is  distributed  with  the  Keyboard  Monitor  TIME  command 
calculations  based  on  a  60-cycle  clock  rate.  To  cause  the  TIME 
command  to  base  calculation  on  a  50-cycle  rate,  the  monitor  is 
modified  such  that  bit  5  (40(8))  is  set  in  the  monitor  configuration 
word  (see  Section  9.2.6).  The  address  of  the  CONFIG  word  in  the  single 
job  monitors  is  33300,  and  35300  in  the  F/B  monitors.  For  example: 

For  the  F/B  monitors 

.R  PATCH 

PATCH  Version  number 

FILE  NAME — 

*RKMNFB. SYS/M 
*35300/1  41 

*E 


For  the  S/J  monitors 
.R  PATCH 

PATCH  Version  number 
FILE  NAME — 

*RKMNSJ. SYS/M 
*33300/0  40 

*E 


A. 3  SYSTEM  OPTIMIZATION 

When  building  RT-11  systems,  performance  can  be  optimized  (especially 
on  DECtape  and  DECpack  disk)  by  proper  placement  of  .SYS  files  on  the 
system  device. 

Optimal  file  placement  is: 

MONITR.SYS 

Most  frequently  used  handler 


Least  frequently  used  handler 

SYSMAC.SML  (if  many  assembly  operations  are 

•  performed) 
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Most  frequently  used  program  (usually  PIP.SAV) 


Least  frequently  used  program 
Considerations  for  the  above  placements  are: 

1.  By  positioning  all  .SYS  files  at  the  beginning  of  the  device, 
movement  of  .SYS  files  is  avoided  during  /S  operations  with 
PIP,  thus  eliminating  the  necessity  to  reboot. 

2.  Placement  of  the  monitor  immediately  following  the  directory 
optimizes  device  motion  during  monitor  swapping  operations. 

3.  Positioning  the  handlers  and  programs  in  descending  order 
related  to  frequency  of  use  reduces  the  access  times  for 
those  files. 

4.  In  systems  that  will  be  used  for  frequent  assembly 
operations,  assembler  performance  can  be  improved  by  placing 
SYSMAC.SML  near  the  beginning  of  the  device. 

DECtape  users  can  also  conserve  time  and  space  by  placing  only  those 
files  needed  on  the  system  DECtape.  Users  of  8K  DECtape  systems  need 
not  place  files  such  as  MACRO. SAV  and  RK.SYS  on  the  system  device,  as 
these  files  cannot  be  used  in  8K  systems. 


A. 4  ASSEMBLY  AND  LINKING  INSTRUCTIONS 


A. 4.1  General  Instructions 

All  RT-11  components,  except  MACRO,  ASEMBL,  and  the  monitors,  require 
16K  of  memory  to  be  assembled.  MACRO,  ASEMBL,  and  the  monitors 
require  20K.  RT-11  MACRO  is  used  as  the  assembler,  and  RT-11  LINK  is 

used  as  the  Linker  in  all  cases.  All  assemblies  (except  ODT)  and  all 
links  (except  RK.SYS,  RF.SYS  and  DT.SYS)  should  be  error  free. 

Throughout  the  following  sections,  the  conventions  used  are: 

1.  Default  extensions  are  not  explicitly  specified.  For  all  the 
source  files,  the  extensions  are  .MAC.  The  assembler  output 
is  .OBJ  and  Linker  output  is  .SAV. 

2.  The  system  macro  library,  SYSMAC.SML,  must  be  on  the  system 
device  during  all  assemblies  given  below. 

3.  In  the  example  command  strings,  the  sources  are  kept  on 
logical  device  SRC:,  binary  output  is  to  device  BIN:,  and 
listing  and  map  files  are  output  to  LST: .  In  actual  practice, 
any  appropriate  device  can  be  used. 

4.  The  example  command  strings  were  executed  on  a  28K  computer 
and  the  "FREE  CORE"  error  messages  reflect  that  fact.  The 
actual  number  of  free  memory  words  in  each  installation  will 
vary,  and  is  not  of  importance. 
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All  RT-11  system  assembling  and  linking  operations  are  normal 
operations,  and  the  command  strings  in  the  descriptions  below  can  be 
altered  to  take  full  advantage  of  all  RT-11  MACRO  and  LINK  command 
features . 


A. 4. 2  Assembling  and  Linking  the  System  Piles 

The  result  of  the  operations  below  is  the  six  monitors  and  ten 
handler  files.  The  UNDEF  GLBLS  messages  resulting  from  RK.SYS,  RF.SYS 
and  DT.SYS  linking  is  expected.  The  monitor  files  are  named  as 
described  in  Section  A. 1.2. 

.R  MACRO 

*BIN : RT11SJ , LST  s  RT11S J»SRC s  KMON , USR, RMONS J , KMOVLY 
ERRORS  DETECTED:  0 
FREE  CORE:  9943.  WORDS 

*BIN : RT11FB , LST : RT11FB=SRC : BFDEF ,KMON , USR , RMONFB , KMOVLY 
ERRORS  DETECTED:  0 
FREE  CORE:  8232.  WORDS 

* B IN : RKBTS J , LS T : RKBTS J=S RC : BS TRAP 
ERRORS  DETECTED:  0 
FREE  CORE:  15687.  WORDS 

*BIN : RFBTS J ,LST : RFBTS J=SRC : RFSYS , BSTRAP 
ERRORS  DETECTED:  0 
FREE  CORE:  15679.  WORDS 

*BIN: DTBTS J, LST : DTBTSJ=SRC : DTSYS , BSTRAP 
ERRORS  DETECTED:  0 
FREE  CORE:  15671.  WORDS 

*BIN : RKBTFB ,LST : RKBTFB=SRC : BFDEF , BSTRAP 
ERRORS  DETECTED:  0 
FREE  CORE:  15659.  WORDS 

*BIN: RFBTFB , LST : RFBTFB=S RC : RFSYS , BFDEF , BSTRAP 
ERRORS  DETECTED:  0 
FREE  CORE:  15651.  WORDS 

*BIN : DTBTFB ,LST : DTBTFB=SRC : DTSYS , BFDEF , BSTRAP 
ERRORS  DETECTED:  0 
FREE  CORE:  15643.  WORDS 

*BIN : RK ,LST : RK=SRC : RK 
ERRORS  DETECTED:  0 
FREE  CORE:  16575.  WORDS 

*BIN:RF,LST:RF=SRC:RF 
ERRORS  DETECTED:  0 
FREE  CORE:  16591.  WORDS 


*BIN:DT,LST:DT=SRC:DT 
ERRORS  DETECTED:  0 
FREE  CORE:  16584.  WORDS 
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*BIN:TT,LST:TT=SRC:TT 
ERRORS  DETECTED:  0 
FREE  CORE:  16562.  WORDS 

•BIN : LP , LST : LP=SRC : LP 
ERRORS  DETECTED:  0 
FREE  CORE:  16564.  WORDS 

*BIN:PR,LST:PR=SRC:PR 
ERRORS  DETECTED:  0 
FREE  CORE:  16670.  WORDS 

•BIN : PP , LST : PP=S  RC : PP 
ERRORS  DETECTED :  0 

FREE  CORE:  16663.  WORDS 

*BIN:CR,LST:CR=SRC:CR 
ERRORS  DETECTED:  0 
FREE  CORE:  16201.  WORDS 

•BIN : MT , LST : MT=S RC : MT 
ERRORS  DETECTED :  0 

FREE  CORE:  15564.  WORDS 

*BIN:CT,LST:CT=SRC:CT 
ERRORS  DETECTED:  0 
FREE  CORE:  15631.  WORDS 

.R  LINK 

•BIN : RKMNFB . SYS , LST : RKMNFB»BIN : RKBTFB , RT11FB , RK 

•BIN : RKMNS J. SYS , LST : RKMNS J«BIN : RKBTS J , RT11S J , RK 

•BIN : RFMNFB . SYS , LST : RFMNFB=BIN : RFBTFB , RT11FB , RF 

•BIN : RFMNS J. SYS ,LST : RFMNS J*BIN : RFBTS J , RT11S J , RF 

•BIN : DTMNFB . SYS , LST : DTMNFB=BIN : DTBTFB , RT11FB , DT 

•BIN : DTMNSJ. SYS , LST : DTMNS  J*»BIN : DTBTSJ , RT11S J , DT 

•BIN : RK . SYS , LST : RK=BIN : RK 
UNDEF  GLBLS 

•BIN : RF . SYS ,LST : RF-BIN : RF 
UNDEF  GLBLS 

•BIN : DT . SYS , LST : DT=BIN : DT 
UNDEF  GLBLS 

•BIN : TT . SYS , LST : TT«BIN : TT 
•BIN : LP . SYS , LST : LP=BIN . LP 
*BIN:PR.SYS,LST:PR«BIN:PR 
•BIN : PP . SYS , LST : PP-BIN : PP 
*BIN:CR.SYS,LST:CR“BIN:CR 
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*BIN:MT.SYS,LST:MT=BIN:MT 

*BIN:CT.SYS,LST:CT»BIN:CT 


A. 4. 3  Assembling  and  Linking  EDIT 
.R  MACRO 

♦BINs  VTCED1 , LST : VTCEDl=S RC : EDITDF , VTCAL1 
ERRORS  DETECTED:  0 
FREE  CORE:  16654.  WORDS 

*BI N : VTCED4 , LST : VTCED4=S RC : EDITDF , VTCAL4 
ERRORS  DETECTED:  0 
FREE  CORE:  16120.  WORDS 

♦BIN : VTBEDT ,  LST : VTBEDT=SRC : EDITDF , VTBASE 
ERRORS  DETECTED :  0 

FREE  CORE:  16415.  WORDS 

♦BIN :EDIT, LST :EDIT=SRC :VTMAC , EDIT 
ERRORS  DETECTED :  0 

FREE  CORE:  12873.  WORDS 

.R  LINK 

♦BIN : EDIT , LST : EDIT=BIN : VTCED1 , VTCED4 , VTBEDT , EDIT 


A. 4.4  Assembling  and  Linking  MACRO 
.R  MACRO 

♦BIN : RTEXEC ,LST : RTEXEC=SRC : RTPAR , RPARAM , RCIOCH , RTEXEC 
ERRORS  DETECTED:  0 
FREE  CORE:  13816.  WORDS 

♦BIN : RTMAC , LST : RTMAC=SRC : RTPAR , RPARAM , RC I OCH , MAC RO  3 , MACRO 5 
ERRORS  DETECTED:  0 
FREE  CORE:  9174.  WORDS 

♦BIN : RTPST , LST : RTPST-SRC : RTPAR, PST 
ERRORS  DETECTED:  0 
FREE  CORE:  16258.  WORDS 

.R  LINK 

♦BIN : MACRO , LST : MACRO»BIN : RTEXEC , RTMAC , RTPST 


A. 4. 5  Assembling  and  Linking  EXPAND 
.R  MACRO 

♦BIN : PREXEC , LST : PREXEC=S RC : PREPAR , PPARAM , PCIOCH , PREXEC 
ERRORS  DETECTED:  0 
FREE  CORE:  15181.  WORDS 

♦ BIN : PREPAS , LS T : PREP AS =S RC : PREPAR , PPARAM , PCIOCH , PREPAS 
ERRORS  DETECTED:  0 
FREE  CORE:  14893.  WORDS 

.R  LINK 

♦BIN : EXPAND , LST :EXPAND=BIN : PREXEC , PREPAS 
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A. 4.6  Assembling  and  Linking  ASEMBL 
.R  MACRO 

♦BIN : SMEXEC ,LST  s  SMEXEC=S  RCsSMPAR, RPARAM , RCIOCH , RTEXEC 
ERRORS  DETECTED:  0 
FREE  CORE:  14059.  WORDS 

♦BIN: SMMAC , LST : SMMAC=S  RC : SMPAR , RPARAM , RCIOCH , MACR03 , MACROS 
ERRORS  DETECTED:  0 
FREE  CORE:  9921.  WORDS 

*BIN : SMPST , LST : SMPST-SRC : SMPAR, PST 
ERRORS  DETECTED:  0 
FREE  CORE:  16254.  WORDS 

.R  LINK 

♦BIN: ASEMBL , LST : AS  EMBL=BIN : SMEXEC , SMMAC , SMPST 


A. 4. 7  Assembling  and  Linking  CREF 
.R  MACRO 

♦BIN:CREF , LST : CREF-SRC : CREF 
ERRORS  DETECTED:  0 
FREE  CORE:  14792.  WORDS 

.R  LINK 

♦BIN : CREF , LST : CREF=BIN : CREF 


A. 4. 8  Assembling  and  Linking  LINK 
.R  MACRO 

♦BIN :  LINKO  ,  LST :  LINK0=*SRC :  LINKO 
ERRORS  DETECTED:  0 
FREE  CORE:  13944.  WORDS 

♦BIN: LNKOV1 , LST : LNKOVl-SRC : LNKOV1 
ERRORS  DETECTED:  0 
FREE  CORE:  14583.  WORDS 

*BIN:LNKOV2 ,LST:LNKOV2=SRC:LNKOV2 
ERRORS  DETECTED:  0 
FREE  CORE:  14834.  WORDS 

♦BIN : LNKOV3 ,LST : LNKOV3=SRC : LNKOV3 
ERRORS  DETECTED:  0 
FREE  CORE:  14530.  WORDS 

♦BIN : LNKOV4 ,LST : LNKOV4»SRC : LNKOV4 
ERRORS  DETECTED:  0 
FREE  CORE:  14726.  WORDS 

♦BIN : LNKOV5 ,LST : LNKOV5=SRC : LNKOV5 
ERRORS  DETECTED:  0 
FREE  CORE:  14434.  WORDS 
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.R  LINK 

*BIN: LINK ,LST  s LINK=BIN  s  LINKO/C 

•BIN : LNKOVl/O : 1/C 

•BIN  s  LNK0V2/0 : 1/C 

•BIN  s  LNK0V3/0 s 1/C 

•BIN  s  LNK0V4/0 s 1/C 

•BIN : LNK0V5/0 : 1 


A. 4. 9  Assembling  and  Linking  LIBR 
.R  MACRO 

•BINs  LIBRO ,LSTs LIBR0=S  RC : LIBRO 
ERRORS  DETECTED:  0 
FREE  CORE:  14480.  WORDS 

•BIN : LIBR1 ,LST : LIBR1=SRC : LIBR1 
ERRORS  DETECTED:  0 
FREE  CORE:  14635.  WORDS 

•BIN : LIBR2 ,LST : LIBR2=SRC : LIBR2 
ERRORS  DETECTED:  0 
FREE  CORE:  14827.  WORDS 

•BIN : LIBR3 ,LST: LIBR3=SRC : LIBR3 
ERRORS  DETECTED:  0 
FREE  CORE:  15068.  WORDS 

•BIN : LIBR4 ,LST : LIBR4=SRC : LIBR4 
ERRORS  DETECTED:  0 
FREE  CORE:  14996.  WORDS 

.R  LINK 

•BIN: LIBR, LST:LIBR=BIN: LIBRO /C 

•BIN : LIBRl/O : 1/C 

•BIN : LIBR2/0 : 1/C 

•BIN : LIBR3/0 : 1/C 

•BIN : LIBR4/0 : 1 


A. 4. 10  Assembling  and  Linking  PIP 


.R  MACRO 

*BIN:PIP,LST:PIP=SRC:PIP 
ERRORS  DETECTED:  0 
FREE  CORE:  13664.  WORDS 

.R  LINK 

*BIN:PIP,LST:PIP»BIN:PIP 


A. 4. 11  Assembling  and  Linking  FILEX 


.R  MACRO 

•BIN : FILEX ,LST :FILEX=SRC  sFILEX 
ERRORS  DETECTED:  0 
FREE  CORE:  12986.  WORDS 


.R  LINK 

•BIN : FILEX ,LST : FILEX=BIN : FILEX 
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A. 4. 12  Assembling  and  Linking  SRCCOM 
.R  MACRO 

*BIN:S RCCOM , LST : S RCCOM=S RC  s  S RCCOM 
ERRORS  DETECTED:  0 
FREE  CORE:  15293.  WORDS 

.R  LINK 

♦BIN : SRCCOM , LST : S  RCCOM=BIN : S  RCCOM 


A. 4 .13  Assembling  and  Linking  DUMP 
.R  MACRO 

♦BIN : DUMP , LST : DUMP-SRC : DUMP 
ERRORS  DETECTED:  0 
FREE  CORE:  15597.  WORDS 

.R  LINK 

♦BIN :  DUMP ,  LST :  DUMP«=BIN :  DUMP 


A. 4. 14  Assembling  and  Linking  PATCH 
.R  MACRO 

♦BIN : PATCH , LST : PATCH=SRC : PATCH 
ERRORS  DETECTED:  0 
FREE  CORE:  15524.  WORDS 

.R  LINK 

♦BIN : PATCH , LST : PATCH=BIN : PATCH 


A. 4.15  Compiling  and  Linking  PATCHO 

PATCHO  is  written  in  FORTRAN,  and  as  such  requires  RT-11  FORTRAN  IV 
for  compilation  and  linking. 

R  FORTRA 

♦BIN : PATO , LST : PAT0=SRC : PATO/S/P/N : 5/R: 120 

♦BIN :PAT1 ,LST : PAT1=SRC :PAT1/S/P 

♦BIN : PAT 2 ,LST : PAT2=SRC :PAT2/S/P 

*BIN:PAT3 ,LST :PAT3=SRC :PAT3/S/P 

♦BIN : PAT 4 ,LST : PAT4=SRC : PAT 4 /S/P 

♦BIN : PAT 5 ,LST : PAT5=S  RC : PAT 5/S /P 

*BIN:PAT6 ,LST:PAT6=SRC:PAT6/S/P 

.R  MACRO 

♦BIN : IRAD50 ,LST : IRAD50=SRC : IRAD50 
ERRORS  DETECTED:  0 
FREE  CORE:  16732.  WORDS 

*BIN:R50ASC,LST:R50ASC=SRC:R50ASC 
ERRORS  DETECTED:  0 
FREE  CORE:  16720.  WORDS 
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The  following  linking  instructions  require  that  the  FORTRAN  library, 
FORLIB . OBJ ,  be  available  on  the  system  device.  FORLIB.OBJ  is 
available  as  part  of  the  RT-11  FORTRAN  Kit. 

. R  LINK 

*BIN  s  PATCH 0=BIN s  PATO/I/C/B  s 110  0/F 

*BIN : PAT1 , IRAD50/O s 1/C 

*BIN s  PAT 3 , R50ASC/0 : 1/C 

*BIN:PAT2/0:2/C 

*BIN:PAT4/0:2/C 

*BIN:PAT5/Os2/C 

*BIN:PAT6/0:2 

LIBRARY  SEARCH: 

$SHORT 


A. 4. 16  Assembling  ODT 

ODT  assembles  with  one  error  (a  "Z"  error  which  flags  an  ODT 
instruction  which  is  machine  dependent) .  The  error  is  necessary  and 
should  be  ignored. 

.R  MACRO 

*BIN : ODT ,LST : ODT=SRC : ODT 
ERRORS  DETECTED:  1 
FREE  CORE:  15730.  WORDS 


A. 4. 17  Assembling  and  Building  the  VT11  Display  Handler  Library 
.R  MACRO 

*BIN : VTCAL1 , LST : VTCAL1*S RC : VTCAL1 
ERRORS  DETECTED:  0 
FREE  CORE:  16658.  WORDS 

*BIN:VTCAL2 , LS T : VTCAL2 =S  RC : VTCAL 2 
ERRORS  DETECTED:  0 
FREE  CORE:  16726.  WORDS 

*BIN : VTCAL3 ,LST : VTCAL3=SRC : VTCAL3 
ERRORS  DETECTED:  0 
FREE  CORE:  16693.  WORDS 

*BIN:VTCAL4 , LS T : VTCAL 4=SRC: VTCAL 4 
ERRORS  DETECTED:  0 
FREE  CORE:  16140  WORDS 

*BIN : VTBASE ,LST : VTBASE=SRC : VTBASE 
ERRORS  DETECTED:  0 
FREE  CORE:  16355.  WORDS 

.R  PIP 

*BIN:VTHDLR.0BJ=BIN:VTCAL1.0BJ,VTCAL2.0BJ,VTCAL3.0BJ,VTCAL4.0BJ,VTBASE.0BJ/B 
.R  LIBR 

*BIN : VTLIB=BIN : VTHDLR 
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COMMAND  AND  SWITCH  SUMMARIES 


Command  and  switch  summaries  of  the  various  RT-11  system  and  utility 
programs  are  grouped  here  for  the  user's  convenience.  Refer  to  the 
appropriate  chapter  for  details. 


B.l  KEYBOARD  MONITOR  (Chapter  2) 


B.1,1  Command  Summary 

Only  those  command  characters  underlined  need  be  entered;  all  command 
lines  are  terminated  by  typing  a  carriage  return. 


Command  Format  Used  Under 


Explanation 


ASSIGN  devjudev  F/B,S/J  Assigns  a  user-defined  name  (udev)  as  an 

alternate  name  for  a  device  (dev) • 
Deassigns  synonyms  when  used  without  any 
arguments • 


B  location 


CLOSE 


F/B,S/J  Sets  a  relocation  base  (location) ,  which 
is  an  octal  address  to  be  used  as  a  base 
address  for  subsequent  Examine  and 
Deposit  commands, 

F/B,S/J  Causes  all  currently  open  files  to  be- 
(B  only)  come  permanent. 


DATE  dd-mmm-yy  F/B,S/J  Enters  the  indicated  day-month-year 

(dd-mmm-yy) ;  this  date  is  then  assigned 
to  newly  created  files ,  new  device 
directory  entries ,  and  listing  output. 
When  used  without  an  argument,  the 
current  date  (as  entered)  is  printed. 

D  location  =  valuel,value2 , . . . ,valuen 

F/B,S/J  Deposits  the  specified  values  starting 
at  the  given  location  (location 

represents  an  octal  address  which  is 
added  to  the  base  address  to  obtain  the 
actual  address  at  which  values  will  be 
deposited) . 
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Command  Format  Used  Under  Explanation 

E  location  m-location  n  Prints  the  contents  of  the  specified 

F/B,S/J  locations  in  octal  on  the  console 

terminal  (location  represents  an  octal 
address  which  is  added  to  the  base 
address  to  obtain  the  actual  address 
examined) . 

FRUN  dev:filnam.ext/N:n/S:n/P  Initiates  a  foreground  job  which  exists 

F/B  on  the  device  indicated  (dev)  under  the 

(F  only)  specified  filename  and  extension.  /N:n 
is  optionally  used  to  allocate  n 
(decimal)  words  over  and  above  actual 
program  size;  /Ssn  is  optionally  used 
to  allocate  n  words  for  stack  space;  /P 
is  used  for  debugging  purposes  (the  load 
address  is  printed  but  the  program  must 
be  started  using  RSUME) . 


GET  devsfilnam.ext 

F/B,S/J 

Loads  the  specified  memory  image  file 
(filnam.ext)  into  memory  from  the 
indicated  device  (dev:) • 

GT  OFF 

F/B,S/J 

Used  (after  GT  ON)  to  clear  the  display 
processor  and  resume  printout  on  the 
console  terminal. 

GT  ON/L:n/T:n 

F/B ,S/J 

Enables  the  display  processor  so  that 
the  display  screen  replaces  the  console 
as  the  terminal  output  device.  /L:n  may 
be  optionally  used  to  designate  the 
number  of  lines  to  display  (12"  screen  - 
l<=n<=37  octal;  17"  screen  -  l<«n<«50 
octal).  /T:n  may  be  optionally  used  to 
indicate  the  top  position  of  the  scroll 
display  (12"  screen  -  l<=n<=1350  octal; 
17"  screen  -  l<=n<=1750  octal) . 

INITIALIZE 

F/B,S/J 
(B  only) 

Resets  background  system  tables;  makes 
nonresident  all  handlers  not  loaded  and 
purges  background's  I/O  channels. 

LOAD  dev#. . . 

F/B,S/J 

Makes  a  device  handler  resident  for  use. 

LOAD  dev=B,dev=F, . . 

. 

F/B 

Makes  a  device  handler  resident  for  use 
with  background  and  foreground  jobs. 

R  filnam.ext 

F/B,S/J 
(B  only) 

Loads  the  specific  memory  image  file 
(filnam.ext)  into  memory  from  the  system 
device  and  starts  execution. 

REENTER 

F/B,S/J 

Starts  a  program  at  its  reentry  address 
(i.e.,  its  start  address  -2). 

RSUME 

F/B 

(F  only) 

Resumes  execution  of  a  foreground 

program  where  it  was  suspended. 

RUN  devsfilnam.ext 

F/B,S/J 
(B  only) 

Loads  the  specified  memory  image  file 
(filnam.ext)  into  memory  from  the 

indicated  device  (devs)  and  starts 
execution. 
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Command  Format  Used  Under  Explanation 

SAVE  devjfilnam.ext  areal, area2-arean 

F/B,S/J  Writes  the  area(s)  of  user  memory 
specified  into  the  named  file 

(filnam.ext)  in  save  image  format. 
Memory  is  transferred  in  256-word 
blocks . 


SET  dev: <NO>option=value 

F/B,S/J  Used  to  change  device  (dev:)  handler 
characteristics  and  certain  system 
configuration  parameters.  See  Table  2-5 
(Section  2. 7. 2. 8)  for  a  list  of  options. 


START  address 


F/B,S/J  Begins  execution  of  the  program 
currently  in  memory  at  the  specified 
address.  If  an  address  is  not 
indicated,  the  starting  address  in 
location  40  is  used. 


SUSPEND 


F/B  Suspends  execution  of  the  foreground  job 

(F  only)  currently  running. 


TIME  hh:mm:ss  F/B,S/J  Enters  time  of  day  in  hours,  minutes, 

seconds  past  midnight  (hh:mm:ss).  If  all 
three  arguments  are  omitted,  the  current 
time  of  day  is  output. 


UNLOAD  dev, dev,...  F/B,S/J  Makes  previously  loaded  handlers  (dev) 

nonresident  and  frees  the  memory  space 
they  were  using. 


B.1.2  Special  Function  Keys 


Key 


Used  Under 


Function 


CTRL  A 


CTRL  B 


F/B,S/J  Valid  when  the  monitor  GT  ON  command 
has  been  typed  and  the  display  is  in 
use.  Does  not  echo  on  the  terminal. 
Used  after  CTRL  S  has  been  typed  to 
effectively  page  output. 

F/B  Echoes  B>  on  the  terminal  and  causes  all 

keyboard  input  to  be  directed  to  the 
background  job.  At  least  one  line  of 
output  will  be  taken  from  the  background 
job  (the  foreground  job  has  priority  and 
control  will  revert  to  it  if  it  has 
output) .  B>  does  not  echo  if  output  is 
already  coming  from  the  background  job. 
(Control  can  be  redirected  to  the 
foreground  job  via  CTRL  F.) 
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Key 

CTRL  C 


CTRL  E 


CTRL  F 


CTRL  0 


CTRL  Q 


CTRL  S 


CTRL  U 


Used  Under  Function 

F/B,S/J  Echoes  tC  on  the  terminal ,  interrupts 
current  program  execution ,  and  returns 
control  to  the  Keyboard  Monitor.  If  a 
program  is  waiting  for  terminal  input  or 
is  using  the  device  handler  TT:  for 

input,  typing  a  single  CTRL  C  interrupts 
execution  and  returns  control  to  the 
monitor  command  level.  Otherwise,  two 
CTRL  C*s  must  be  typed  in  order  to 
interrupt  execution. 

F/B ,S/J  Valid  when  the  monitor  GT  ON  command  has 

been  typed  and  the  display  is  in  use. 
Does  not  echo  on  the  terminal,  but 
causes  all  I/O  to  appear  on  both  the 
display  screen  and  the  console  terminal 
simultaneously.  A  second  CTRL  E 

disables  console  terminal  output. 

F/B  Echoes  F>  on  the  terminal  and  directs 

all  keyboard  input  to  the  foreground  job 
and  all  output  to  be  taken  from  the 
foreground  job.  Control  remains  with 
the  foreground  job  until  redirected  to 
the  background  job  (via  CTRL  B)  or  until 
the  foreground  job  terminates. 


F/B,S/J  Echoes  to  on  the  terminal  and  causes 
suppression  of  teleprinter  output  while 
continuing  program  execution. 

Teleprinter  output  is  reenabled  when  one 
of  the  following  occurs: 


1.  A  second  CTRL  0  is  typed 

2.  A  return  to  the  monitor  is 
indicated  via  CTRL  C 

3.  The  running  program  issues  a 

• RCTRLO  directive  (see 

Chapter  9) 

F/B,S/J  Does  not  echo.  Resumes  printing 

characters  on  the  terminal  from  the 

point  at  which  printing  was  previously 
stopped  (via  CTRL  S) • 

F/B , S / J  Does  not  echo.  Temporarily  suspends 

output  to  the  terminal  until  a  CTRL  Q  is 
typed.  If  GT  ON  is  in  effect,  each 
subsequent  CTRL  A  causes  output  to 

proceed  until  the  screen  has  been 
refilled  once. 


F/B,S/J  Echoes  tU  followed  by  a  carriage  return 
on  the  terminal  and  deletes  the  current 
input  line. 


Echoes  tZ  on  the  terminal  and  terminates 
input  when  used  with  the  terminal  device 
handler  (TT:). 
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Key  Used  Under  Function 

RUBOUT  F/B,S/J  Deletes  the  last  character  from  the 

current  line.  Echoes  a  backslash  plus 
the  character  deleted;  each  succeeding 
RUBOUT  deletes  and  echoes  another 
character;  an  enclosing  backslash  is 
printed  when  a  key  other  than  RUBOUT  is 
typed. 


B.2  EDITOR  (Chapter  4) 


B . 2 . 1  Command  Arguments 

Format  Meaning 

n  A  decimal  integer  (in  the  range  -16383  to  +16383)  which  may, 

except  where  noted,  be  preceded  by  a  +  or  -.  Whenever  an 
argument  is  acceptable  in  a  command,  its  absence  implies  an 
argument  of  1. 

0  Refers  to  the  beginning  of  the  current  line. 

/  Refers  to  the  end  of  the  text  in  the  current  Text  Buffer. 

“  Is  used  with  the  J,  D  and  C  commands  only  and  represents  — n, 

where  n  is  equal  to  the  length  of  the  last  text  argument 
used. 


B.2. 2  Input  and  Output  Commands 


Command 
EDIT  BACKUP 

EDIT  READ 

EDIT  WRITE 

END  FILE 

EXIT 

LIST 


Form  Meaning 

EB  dev:f ilnam.ext [n] $ 

Opens  a  file  for  editing,  creating  a 
backup  copy  (.BAK). 

ER  dev:filnam.ext$ 

Opens  a  file  for  input. 

EW  dev :f ilnam.ext [n] $ 

Creates  a  new  file  for  output. 

EF  Closes  the  current  output  file  without 

performing  any  further  input/output 
operations. 

EX  Outputs  the  remainder  of  the  input  file 

to  the  output  file  and  returns  control 
to  the  monitor. 

(— )nL  Prints  a  specified  number  of  lines  on 

OL  the  console  terminal. 

/L 
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Command 

NEXT 

READ 

VERIFY 

WRITE 


Form 


nN 


R 


V 


(-)nW 

OW 

/W 


Meaning 

Outputs  the  contents  of  the  Text  Buffer 
to  the  output  file,  clears  the  buffer, 
and  reads  in  the  next  page  of  the  input 
file. 

Reads  a  page  of  text  from  the  input  file 
and  appends  it  to  the  contents  of  the 
buffer. 

Prints  the  current  text  line  (the  line 
containing  the  pointer)  on  the  console 
terminal. 

Outputs  a  specified  number  of  lines  of 
text  from  the  Text  Buffer  to  the  output 
file. 


B.2.3  Pointer  Relocation  Commands 


Command 

ADVANCE 


BEGINNING 

JUMP 


Form 


(-)nA 

OA 

/A 


B 


(-)nJ 

OJ 

/J 

=J 


Meaning 

Moves  the  pointer  over  a  specified 
number  of  lines  in  the  Text  Buffer.  The 
pointer  is  positioned  at  the  beginning 
of  the  line. 

Moves  the  current  location  pointer  to 
the  beginning  of  the  Text  Buffer. 

Moves  the  pointer  over  a  specified 
number  of  characters  in  the  Text  Buffer. 


B.2.4  Search  Commands 
Command  Form 

FIND  nFtext$ 


GET  nGtext$ 


POSITION  nPtext$ 


Meaning 


Beginning  at  the  current  location 
pointer,  searches  the  entire  text  file 
for  the  nth  occurrence  of  the  specified 
character  string.  Pages  of  text  are 
read  into  the  Text  Buffer,  searched,  and 
then  written  to  the  output  file  until 
the  text  string  is  found. 

Searches  the  contents  of  the  Text 
Buffer,  beginning  at  the  current 
location  pointer,  for  the  next 
occurrence  of  the  text  string. 

Searches  the  input  file  for  the  nth 
occurrence  of  the  text  string;  if  the 
text  string  is  not  found,  the  buffer  is 
cleared  and  a  new  page  is  read  from  the 
input  file. 
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B.2.5  Text  Modification  Commands 


Command 

Form 

Meaning 

CHANGE 

(-)nCtext$ 

0Ctext$ 

/Ctext$ 

Replaces  n  characters,  beginning  at 
the  pointer,  with  the  indicated 
text  string. 

DELETE 

(-)nD 

OD 

/D 

=D 

Removes  a  specified  number  of 
characters  from  the  Text  Buffer, 
beginning  at  the  current  location 
pointer. 

EXCHANGE 

(-)nXtext$ 

0Xtext$ 

/Xtext$ 

Replaces  n  lines,  beginning  at  the 
pointer,  with  the  indicated  text 
string. 

INSERT 

Itext$ 

Inserts  text  immediately  following  the 
current  location  pointer;  an  ALTMODE 
terminates  the  text. 

KILL 

(-)nK 

OK 

/K 

Removes  n  lines  from  the  Text  Buffer 
beginning  at  the  current  location 
pointer. 

c 


B.2.6  Utility  Commands 
Command  Form 

EDIT  CONSOLE  EC 


EDIT  DISPLAY  ED 


Meaning 

If  scroller  is  in  use,  EC  returns 
scroller  to  its  normal  mode  (using  full 
screen  for  display  of  text  and 
commands);  if  scroller  is  not  in  use, 
EC  clears  screen  and  returns  control  to 
console  terminal  (following  ED) • 

If  scroller  is  in  use,  ED  recalls  the 
text  window  (following  EC)  and  arranges 
text  and  commands  on  screen;  if 
scroller  is  not  in  use,  ED  displays 
text  window  only. 


EXECUTE  MACRO 

MACRO 


SAVE 


nE  Executes  the  command  string  specified 

in  the  last  macro  command. 

M/command  string/ 

Inserts  a  command  string  into  the  Macro 
Buffer, 

OM  Clears  the  Macro  Buffer  and  reclaims 

M//  the  area  for  text. 

nS  Copies  the  specified  number  of  lines, 

beginning  at  the  pointer,  into  the  Save 
Buffer. 

Inserts  the  entire  contents  of  the  Save 
Buffer  into  the  Text  Buffer  at  the 
position  of  the  current  location 

pointer. 
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Command  Form 

Meaning 

EDIT  VERSION  EV 

Displays  the  version  number  of  the 
Editor  on  the  console  terminal. 

B.2.7  Immediate  Mode  Commands 

Command  Meaning 


CTRL  N 

Advances  the  pointer  (cursor)  to  the 
beginning  of  the  next  line. 

CTRL  G 

Moves  the  pointer  (cursor)  to  the 

beginning  of  the  previous  line. 

CTRL  D 

Moves  the  pointer  (cursor)  forward  by 
one  character. 

CTRL  V 

Moves  the  pointer  (cursor)  back  by  one 
character. 

RUBOUT 

Deletes  the  character  immediately 

preceding  the  pointer  (cursor) . 

ALTMODE  (two) 

(one  only) 

Enters  Immediate  Mode. 

Returns  control  to  Editor  Command  Mode. 

Any  character  other 
than  the  above  (with 
the  exception  of  CTRL  C) 

Inserts  the  character  as  text  positioned 
immediately  before  the  pointer  (cursor) . 

B.2.8  Key  Commands 


Command 

Meaning 

ALTMODE 

Echoes  $•  A  single  ALTMODE  terminates  a 
text  string.  A  double  ALTMODE  executes 
the  command  string.  (When  used  alone  on 
a  line,  two  ALTMODES  cause  control  to 
enter  Immediate  Mode,  while  a  single 
ALTMODE  returns  control  to  Editor 
Command  Mode.) 

CTRL  C 

Echoes  at  the  terminal  as  tC  and  a 
carriage  return.  Terminates  execution 
of  EDIT  commands,  closes  any  open  files, 
and  returns  to  monitor  command  mode. 

CTRL  0 

Echoes  to  and  a  carriage  return. 
Inhibits  printing  on  the  terminal  until 
completion  of  the  current  command 
string.  Typing  a  second  CTRL  0  resumes 
output. 

CTRL  U 

Echoes  tU  and  a  carriage  return. 
Deletes  all  the  characters  on  the 
current  terminal  input  line. 

B-8 

Command  and  Switch  Summaries 


Command 

RUBOUT 

TAB 


CTRL  X 


Meaning 

Deletes  character  from  the  current  line. 

Spaces  to  the  next  tab  stop.  Tab  stops 
are  positioned  every  eight  spaces  on  the 
terminal. 

Echoes  tX  and  a  carriage  return.  CTRL  X 
causes  the  Editor  to  ignore  the  entire 
command  string  currently  being  entered. 
The  Editor  prints  a  <CRXLF>  and  an 
asterisk  to  indicate  that  the  user  may 
enter  another  command. 


B.3  PIP  (Chapter  4) 


B.3.1  Switch  Summary 


Switch 

Explanation 

/A 

Copies  file(s)  in  ASCII  mode;  ignores  nulls 
rubouts;  converts  to  7-bit  ASCII. 

and 

/B 

Copies  files  in  formatted  binary  mode. 

/c 

Used  in  conjunction  with  another  switch;  causes 
only  files  with  current  date  to  be  included  in 
the  specified  operation. 

/D 

Deletes  file(s)  from  specified  device. 

/E 

Lists  the  device  directory  including  unused 
spaces  and  their  sizes.  Sequence  numbers  are 
listed  for  cassettes. 

/F 

Prints  a  short  directory  (filenames  only)  of 
specified  device. 

the 

/G 

Ignores  any  input  errors  which  occur  during 
file  transfer  and  continues  copying. 

a 

/I  or  no 
switch 

Copies  file(s)  in  image  mode  (byte  by  byte). 

/K  Scans  the  specified  device  and  types  the  absolute 

block  numbers  (in  octal)  of  any  bad  blocks  on  the 
device. 

/I*  Lists  the  directory  of  the  specified  device. 

Sequence  numbers  are  listed  for  cassettes. 

/Msn  Used  when  I/O  transfers  involve  either  cassette 

or  magtape,  n  represents  the  numeric  position  of 
the  file  to  be  accessed  in  relation  to  the 
physical  position  of  the  cassette  or  magtape  on 
the  drive. 
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Switch 

Explanation 

/Nsn 

Used  with  /Z  to  specify  the  number  of  directory 
blocks  (n)  to  allocate  to  the  directory. 

/o 

Bootstraps  the  specified  device  (DTO ,  RKn ,  or  RF 
only) . 

/Q 

Causes  PIP  to  type  each  filename  which  is 
eligible  for  a  wild  card  operation  and  to  ask  for 
a  confirmation  of  its  inclusion  in  the  operation. 

/R 

Renames  the  specified  file* 

/s 

Compresses  the  files  on  the  specified  directory 
device  so  that  free  blocks  are  combined  into  one 
area. 

A 

Extends  number  of  blocks  allocated  for  a  file. 

/U 

Copies  the  bootstrap  from  the  specified  file  into 
absolute  blocks  0  and  2  of  the  specified  device. 

A 

Types  the  version  number  of  the  PIP  program  being 
used. 

A 

Includes  the  absolute  starting  block  and  any 
extra  directory  words  in  the  directory  listing 
for  each  file  on  the  device  (numbers  in  octal) . 
Used  with  /F,  /L,  or  /E. 

/X 

Copies  files  individually  (without 

concatenation) . 

A 

Causes  system  flies  and  .BAD  files  to  be  operated 
on  by  the  command  specified. 

/Z  :n 

Zeroes  (initializes)  the  directory  of  the  speci¬ 
fied  device;  h  is  used  to  allocate  extra  words 
per  directory  entry.  When  used  with  /N,  the 
number  of  directory  segments  for  entries  may  be 
specified. 

B.4  MACRO/CREF 

(Chapter  5) 

Refer  to  Appendix  C  for  a  complete  summary  of  MACRO  features.  CREP 
switches  are  also  included  in  that  appendix. 
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B.5  LINKER  (Chapter  6) 


B . 5 . 1  Swi tch  Summary 

The  Linker  switches  (and  the  command  line  on  which  each  must  appear) 
are: 


Switch 

Name 

Command 

Line 

Meaning 

/A 

1st 

Alphabetizes  the  entries  in  the  load  map. 

/B:n 

1st 

Bottom  address  of  program  is  indicated  as  n 
(illegal  for  foreground  links) . 

/c 

any 

Continues  input  files  on  another  command  line 
(must  be  used  with  /0) . 

/F 

1st 

Indicates  that  the  Linker  will  use  the 

default  FORTRAN  library,  FORLIB.OBJ. 

/I 

1st 

Includes  the  global  symbols  to  be  searched 
from  the  library. 

/L 

1st 

Produces  an  output  file  in  LDA  format 

(illegal  for  foreground  links). 

/M:n 

1st 

Allows  terminal  keyboard  specification  of  the 
user's  stack  address.  n  represents  an 
optional  6-digit  unsigned  octal  number. 

/0:n 

any  but 
the  1st 

Indicates  that  the  program  will  be  an  over¬ 
lay  structure;  n  specifies  the  overlay 
region  to  which  the  module  is  assigned. 

/R 

1st 

Produces  output  in  REL  format;  only  files  in 
REL  format  will  run  in  the  foreground  (REL 
format  files  may  not  be  run  under  a 
Single-Job  system) . 

/s 

1st 

Allows  the  maximum  amount  of  space  in  memory 
to  be  available  for  the  Linker's  symbol 
table.  (This  switch  should  only  be  used  when 
a  particular  link  stream  causes  a  symbol 
table  overflow.) 

/T  or 
/T:n 

1st 

Transfer  address  is  to  be  specified  at 

terminal  keyboard  via  n. 
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B.6  LIBRARIAN  (Chapter  7) 


B .  6 . 1  Switch  Summary 

The  Librarian  (LIBR)  switches  ( and  the  command  line  on  which  each  must 
appear)  are: 


Switch 

Command 

Line 

Meaning 

/c 

Any 

The  command  is  too  long  for  the  current 
and  is  continued  on  the  next  line. 

line 

/D 

1st 

Deletes  modules  from  a  library  file. 

/G 

1st 

Global  deletion;  deletes  entry  points 
the  library  directory. 

from 

/R 

1st 

Replaces  modules  in  a  library  file. 

/u 

1st 

Update;  inserts  and  replaces  modules 

in  a 

library  file. 


B.7  ODT  (Chapter  8) 


B.7.1  Command  Summary 

In  the  command  format  shown  below,  r  represents  a  relocatable 
expression  and  n  represents  an  octal  number. 

Command  Format  Explanation 


RETURN 

LINE  FEED 
t  or  A  t  or  A 


Closes  open  location  and  accepts  the  next 
command. 

Closes  current  location  and  opens  next 
sequential  location. 

Opens  previous  location. 


«-  or 


> 


< 

@ 


•*-  or  _  Indexes  the  contents  of  the  opened  location 

by  the  contents  of  the  PC  and  opens  the 
resulting  location. 

>  Uses  the  contents  of  the  opened  location  as  a 

relative  branch  instruction  and  opens  the 
referenced  location. 

<  Returns  to  sequence  prior  to  last  >,  or  +• 

command  and  opens  the  succeeding  location. 

@  Uses  the  contents  of  the  opened  location  as 

an  absolute  address  and  opens  that  location. 
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Command 

Format 

Explanation 

/ 

/ 

Reopens  the  last  opened  location. 

r/ 

Opens  the  word  at  location  r. 

\ 

\ 

Reopens  the  last  opened  byte  (SHIFT  L) . 

r\ 

Opens  the  byte  at  location  r. 

l 

I 

After  a  word  or  byte  has  been  opened,  prints 

ni 

the  address  of  the  opened  location  relative 
to  relocation  register  n.  If  n  is  omitted, 
ODT  selects  the  relocation  register  whose 
contents  are  closest  to  but  less  than  or 
equal  to  the  address  of  the  opened  location. 

$ 

$n/ 

Opens  general  register  n  (0-7) . 

$B/ 

Opens  the  first  word  of  the  breakpoint  table. 

$c/ 

Opens  Constant  Register. 

$F/ 

Opens  Format  Register. 

$P/ 

Opens  Priority  Register. 

$R/ 

Opens  first  Relocation  Register  (register  0) . 

$s/ 

Opens  Status  Register. 

A 

r;nA 

Starting  at  location  r,  prints  n  bytes  in 
their  ASCII  format;  then  inputs  n  bytes  from 
the  terminal  starting  at  location  r. 

B 

;B 

Removes  all  Breakpoints. 

r;B 

Sets  Breakpoint  at  location  r. 

r;nB 

Sets  Breakpoint  n  at  location  r. 

;nB 

Removes  the  nth  Breakpoint. 

C 

r?C 

Prints  the  value  of  r  and  stores  it  in  the 
Constant  Register. 

E 

rjE 

Searches  for  instructions  that  reference 

effective  address  r. 

F 

;F 

Fills  memory  words  with  contents  of  the 
Constant  Register. 

G 

r;G 

Goes  to  location  r  and  starts  program. 

I 

;i 

Fills  memory  bytes  with  the  low-order  8  bits 
of  the  Constant  Register. 

0 

r;0 

Calculates  offset  from  currently  open 

location  to  r. 

P 

;P 

Proceeds  with  program  execution  from 
breakpoint.  In  single  instruction  mode  only, 
executes  next  instruction. 
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Command  Format 

Explanation 

k;P 

Proceeds  with  program  execution  from 
breakpoint;  stops  after  encountering  the 
breakpoint  k  times.  In  single  instruction 
mode  only,  executes  next  k  instructions. 

R  ;R 

Sets  all  Relocation  Registers  to  -1  (highest 
address  value) . 

;nR 

Sets  Relocation  Register  n  to  -1. 

r;nR 

Sets  Relocation  Register  n  to  the  value  of  r. 
If  n  is  omitted,  it  is  assumed  to  be  0. 

R 

Selects  the  Relocation  Register  whose 
contents  are  closest  to  but  less  than  or 
equal  to  contents  of  the  opened  location. 
Subtracts  the  contents  of  the  register  from 
the  contents  of  the  opened  word  and  prints 
the  result. 

nR 

Subtracts  the  contents  of  the  Relocation 
Register  n  from  the  contents  of  the  opened 
word  and  prints  the  result. 

S  ?S 

Disables  single  instruction  mode;  reenables 

breakpoints. 

;nS 

Enables  single  instruction  mode  (n  can  have 
any  value  and  is  not  significant) ;  disables 
breakpoints. 

W  r;W 

Searches  for  words  with  bit  patterns  which 
match  r. 

X  X 

Performs  a  Radix  50  unpack  of  the  binary 
contents  of  the  current  opened  word;  then 
permits  the  storage  of  a  new  Radix  50  binary 
number  in  the  same  location. 

B.8  PROGRAMMED  REQUESTS  (Chapter  9) 

Appendix  E  summarizes  the  programmed  requests  available  under  RT-11, 
Version  2. 

B.9  DUMP  (Appendix  I) 

B.9.1  Switch  Summary 


Switch 

Meaning 

/B 

Outputs  octal  bytes. 

/E:n 

Ends  output  at  block  n. 
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Switch 

Meaning 

/G 

Ignores  input  errors. 

A 

Suppresses  ASCII  output. 

/Osn 

Outputs  only  block  number  n. 

/Ssn 

Starts  output  with  block  n. 

A 

Outputs  octal  words. 

/X 

Outputs  RAD50  characters. 

10  FILEX  (Appendix  J) 

10.1  Switch  Summary 

Switch 

Meaning 

/A 

Indicates  a  character-by-character  ASCII 
transfer  in  which  rubouts  and  nulls  are 
deleted;  when  /T  is  also  used,  each  PDP-10 
word  is  assumed  to  contain  five  7-bit  ASCII 
bytes . 

/D 

Deletes  the  named  file  from  the  device; 
valid  only  for  DOS/BATCH  and  RSTS-11  DECtape. 

/F 

Causes  a  "fast"  listing  of  the  device 

directory  by  listing  filenames  only. 

/I 

Performs  an  image  mode  transfer;  if  the 
input  is  either  DOS/BATCH,  RSTS-11  or  RT-11, 
this  is  a  word-for-word  transfer;  if  the 
input  is  from  DECsystem-10 ,  /I  indicates  that 
the  file  resembles  a  file  created  on 
DECsystem-10  by  MACY11,  MACXll,  or  LNKXll 
with  the  /I  switch:  in  this  case,  each 
DECsystem-10  36-bit  word  contains  one  PDP-11 
8-bit  byte  in  its  low-order  bits. 

/I* 

Causes  a  complete  listing  of  the  device 
directory,  including  filenames,  block 
lengths,  and  creation  dates. 

/P 

Performs  a  packed  image  transfer;  if  the 
input  is  from  either  DOS /BATCH,  RSTS-11  or 
RT-11,  this  is  a  word-for-word  transfer;  if 
the  input  is  from  DECsystem-10,  /P  indicates 
that  the  file  resembles  a  file  created  on 
DECsystem-10  by  MACY11,  MACXll,  or  LNKXll 
with  the  /P  switch,  in  which  case  each 
DECsystem-10  36-bit  word  contains  four  PDP-11 
8-bit  bytes  aligned  on  bits  0,  8,  18,  and  26. 
This  mode  is  assumed  if  no  mode  switch  (/A, 
/I)  is  indicated  in  a  command  line. 
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Switch  Meaning 

/S  Indicates  the  device  is  a  DOS/BATCH  (or 

RSTS-11)  file-structured  device. 

/T  Indicates  the  device  is  a  DECsystem-10 

file-structured  device. 

/V  Types  out  version  number  of  FILEX. 

/Z  Zeroes  the  directory  of  the  specified  device 

in  the  proper  format  (valid  only  for 
DOS/BATCH  and  RSTS-11  DECtape) . 


B. 11  SRCCOM  (Appendix  K) 


B. 11. 1  Switch  Summary 


Switch 

/B 

/C 


/F 


/H 


/Lsn 


/S 


Meaning 

Compares  blank  lines.  Without  this  switch, 
blank  lines  are  ignored. 

Ignores  comments  (all  text  on  a  line  preceded 
by  a  semicolon)  and  spacing  (spaces  and 
tabs) . 

Includes  form  feeds  in  the  output  file  (form 
feeds  are  still  compared  if  /F  is  not  used, 
but  they  are  not  included  in  the  output  of 
differences) . 

Types  list  of  switches  available  (help  text) . 

Specifies  the  number  of  lines  that  determine 
a  match  (where  n  is  an  octal  number  <=310 ) . 
The  default  value  for  n  is  3. 

Ignores  spaces  and  tabs. 


B.12  PATCH  (Appendix  L) 


B . 1 2 . 1  Command  Summary 
Command 


/O 

/M 


Vr;nR 

b:B 


Meaning 

Indicates  overlay-structured  file. 
Indicates  monitor  file. 

Sets  relocation  register  n  to  value  Vr. 
Sets  bottom  address  of  overlay  file  to  b. 
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Command 
[s :] r ,0/ 

[s  :]r  ,o\ 

<CR> 

<LF> 

t  or  A 

@ 

F 

E 


Meaning 

Opens  word  location  Vr  +  o  in  overlay  segment 
s. 

Opens  byte  location  Vr  +  o  in  overlay  segment 
s. 

Closes  currently  open  word/by te. 

Closes  currently  open  word/byte  and  opens  the 
next  one. 

Closes  the  currently  open  word/byte  and  opens 
the  previous  one* 

Closes  the  currently  open  word  and  opens  the 
word  addressed  by  it. 

Begins  patching  a  new  file. 

Exits  to  RT-11  monitor. 


B.13  PATCHO  (Appendix  M) 


B . 13 • 1  Command  Summary 


Command 

BYTE 

DEC 

DUMP 

EXIT 

HELP 

LIST 

OPEN 


Format 


Meaning 


BYTE 


I#)  NAME  OF 
% } CSECT  OR 
) GLOBAL 


OFFSET 


Modifies  a  given  byte  in  an  object  module. 


♦DEC  Used  when  the  proper  checksum  for  the  patch 

being  made  is  unknown.  PATCHO  computes  a 
checksum  and  prints  out  its  value. 

♦DUMP  Prints  the  contents  of  an  object  module  in 

octal  and  causes  an  automatic  POINT  to  the 
next  module,  if  any,  in  the  input  file. 

♦EXIT  Terminates  the  patch  session  by  closing  the 

file  and  returning  control  to  the  monitor. 

♦HELP  Prints  an  explanation  of  the  PATCHO  commands. 

♦LIST  Lists  the  names  of  all  object  modules  in  the 

input  file  in  the  order  in  which  they  appear 
in  the  file.  (A  POINT  command  should  be  used 
after  a  LIST.) 


♦OPEN  Opens  files  for  input  and  output. 
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Command 

POINT 


WORD 


Format  Meaning 
* POINT  modnam 

Locates  the  specified  object  module  (modnam) 
and  prepares  it  for  subsequent  WORD,  BYTE,  or 
DUMP  operations* 


#)name  of  (  +  ) 

WORD  CSECT  +  OFFSET  =  j% /CSECT  OR  j - (OFFSET 
NAME  (  ) GLOBAL  (  ) 

Modifies  a  given  word  in  an  object  module. 


APPENDIX  C 

MACRO  ASSEMBLER,  INSTRUCTION,  AND  CHARACTER  CODE  SUMMARIES 


C.l  ASCII  CHARACTER  SET 


Even 

Parity 

Bit 

7-Bit 

Octal 

Code 

Character 

Remarks 

0 

000 

NUL 

Null,  Tape  Feed,  CTRL  SHIFT  P. 

1 

001 

SOH 

Start  of  Heading;  also  SOM  (Start  Of 

1 

002 

STX 

Message) ,  CTRL  A. 

Start  of  Text;  also  EOA  (End  Of  Address) , 

0 

003 

ETX 

CTRL  B. 

End  of  Text;  also  EOM  (End  Of  Message) , 

1 

004 

EOT 

CTRL  C. 

End  of  Transmission  (END) ;  Shuts  off  TWX 

0 

005 

ENQ 

machines,  CTRL  D. 

Enquiry  (ENQRY) ;  also  WRU,  CTRL  E. 

0 

006 

ACK 

Acknowledge;  also  RU,  CTRL  F. 

1 

007 

BEL 

Rings  the  Bell.  CTRL  G. 

1 

010 

BS 

Backspace;  also  FEO,  Format  Effector. 

0 

Oil 

HT 

Backspaces  some  machines,  CTRL  H. 
Horizontal  TAB.  CTRL  I. 

0 

012 

LF 

Line  Feed  or  Line  Space  (New  Line) ; 

1 

013 

VT 

Advances  paper  to  next  line;  duplicated 
by  CTRL  J. 

Vertical  TAB  (VTAB) .  CTRL  K. 

0 

014 

FF 

FORM  FEED  to  top  of  next  page  (PAGE) . 

1 

015 

CR 

CTRL  L. 

Carriage  Return  to  beginning  of  line. 

1 

016 

SO 

Duplicated  by  CTRL  M. 

Shift  Out;  Changes  ribbon  color  to  red. 

0 

017 

SI 

CTRL  N. 

Shift  In;  Changes  ribbon  color  to  black. 

1 

020 

DLE 

CTRL  0. 

Data  Link  Escape.  CTRL  B  (DC0) . 

0 

021 

DC1 

Device  Control  1,  turns  transmitter 

0 

022 

DC2 

(reader)  on,  CTRL  Q  (X  ON) . 

Device  Control  2,  turns  punch  or  auxiliary 

1 

023 

DC3 

on,  CTRL  R  (TAPE,  AUX  ON). 

Device  Control  3 ,  turns  transmitter 

0 

024 

DC4 

(reader)  off,  CTRL  S  (X  OFF). 

Device  Control  4,  turns  punch  or  auxiliary 

1 

025 

NAK 

Off,  CTRL  T  (AUX  OFF) . 

Negative  Acknowledge;  also  ERR,  Error, 

CTRL  U. 
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1 

026 

SYN 

0 

027 

ETB 

0 

030 

CAN 

1 

031 

EM 

1 

032 

SUB 

0 

033 

ESC 

1 

034 

FS 

0 

035 

GS 

0 

036 

RS 

1 

037 

US 

1 

040 

SP 

0 

041 

i 

0 

042 

N 

1 

043 

# 

0 

044 

$ 

1 

045 

% 

0 

046 

& 

0 

047 

I 

0 

050 

( 

0 

051 

) 

1 

052 

* 

0 

053 

+ 

1 

054 

9 

0 

055 

0 

056 

• 

1 

057 

/ 

0 

060 

0 

1 

061 

1 

1 

062 

2 

0 

063 

3 

1 

064 

4 

0 

065 

5 

0 

066 

6 

1 

067 

7 

1 

070 

8 

0 

071 

9 

0 

072 

: 

1 

073 

; 

0 

074 

< 

1 

075 

s 

1 

076 

> 

0 

077 

? 

1 

100 

0 

0 

101 

A 

0 

102 

B 

1 

103 

C 

0 

104 

D 

1 

105 

E 

1 

106 

F 

0 

107 

G 

0 

110 

H 

1 

111 

I 

1 

112 

J 

0 

113 

K 

1 

114 

L 

0 

115 

M 

0 

116 

N 

1 

117 

0 

0 

120 

P 

1 

121 

Q 

Synchronous  Pile  (SYNC) ,  CTRL  V. 

End  of  Transmission  Block;  also 
Logical  End  of  Medium,  CTRL  W. 
Cancel  (CANCL) ,  CTRL  X. 

End  of  Medium,  CTRL  Y. 

Substitute,  CTRL  Z. 

Escape,  CTRL  SHIFT  K. 

File  Separator,  CTRL  SHIFT  L. 

Group  Separator,  CTRL  SHIFT  M. 

Record  Separator,  CTRL  SHIFT  N. 

Unit  Separator,  CTRL  SHIFT  0, 

Space. 


Apostrophe  or  Acute  Accent. 


LEM, 
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1 

122 

R 

0 

123 

S 

1 

124 

T 

0 

125 

U 

0 

126 

V 

1 

127 

W 

1 

130 

X 

0 

131 

Y 

0 

132 

Z 

1 

133 

[ 

SHIFT  K. 

0 

134 

\ 

SHIFT  L. 

1 

135 

] 

SHIFT  M. 

1 

136 

t 

(Appears  as  ~ 

0 

137 

4- 

(Appears  as 

x 

machines) . 

0 

140 

Accent  Grave. 

1 

141 

a 

1 

142 

b 

0 

143 

c 

1 

144 

d 

0 

145 

e 

0 

146 

f 

1 

147 

g 

1 

150 

h 

0 

151 

i 

0 

152 

j 

1 

153 

k 

0 

154 

1 

1 

155 

m 

1 

156 

n 

0 

157 

o 

1 

160 

P 

0 

161 

q 

0 

162 

r 

1 

163 

s 

0 

164 

t 

1 

165 

u 

1 

166 

V 

0 

167 

w 

0 

170 

X 

1 

171 

Y 

1 

172 

z 

0 

173 

{ 

1 

174 

1 

0 

175 

} 

This  Code  Gene: 

0 

176 

This  Code  Gei 

Present) 

1 

177 

DEL 

DELETE,  RUBOUT 

C.2 

RADIX-50 

CHARACTER 

SET 

on  some  machines ) • 

_  (Underscore)  on 


some 


by  PREFIX  key  (if 


Character 


ASCII  Octal  Equivalent 


Radix- 50  Equivalent 


space  40  0 

A-Z  101-132  1-32 
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$ 

44 

33 

• 

56 

34 

unused 

35 

G\ 

i 

o 

60-71 

36-47 

The  maximum  Radix-50  value  is. 

thus : 

2 

47*50  +47*50+47=174777 

The  following  table  provides  a  convenient  means  of  translating  between 
the  ASCII  character  set  and  its  Radix-50  equivalents.  For  example, 
given  the  ASCII  string  X2B,  the  Radix-50  equivalent  is  (arithmetic  is 
performed  in  octal) : 

X=113000 

2=002400 

B=000002 

X2B-115402 


Single  Char. 

or  Second 

First  Char.  Character 


Third 

Character 


A 

003100 

A 

000050 

A 

000001 

B 

006200 

B 

000120 

B 

000002 

C 

011300 

C 

000170 

C 

000003 

D 

014400 

D 

000240 

D 

000004 

E 

017500 

E 

000310 

E 

000005 

F 

022600 

F 

000360 

F 

000006 

G 

025700 

G 

000430 

G 

000007 

H 

031000 

H 

000500 

H 

000010 

I 

034100 

I 

000550 

I 

000011 

J 

037200 

J 

000620 

J 

000012 

K 

042300 

K 

000670 

K 

000013 

L 

045400 

L 

000740 

L 

000014 

M 

050500 

M 

001010 

M 

000015 

N 

053600 

N 

001060 

N 

000016 

0 

056700 

0 

001130 

0 

000017 

P 

062000 

P 

001200 

P 

000020 

Q 

065100 

Q 

001250 

Q 

000021 

R 

070200 

R 

001320 

R 

000022 

S 

073300 

S 

001370 

S 

000023 

T 

076400 

T 

001440 

T 

000024 

U 

101500 

U 

001510 

U 

000025 

V 

104600 

V 

001560 

V 

000026 

W 

107700 

W 

001630 

W 

000027 

X 

113000 

X 

001700 

X 

000030 

Y 

116100 

Y 

001750 

Y 

000031 

Z 

121200 

Z 

002020 

Z 

000032 

$ 

124300 

$ 

002070 

$ 

000033 

• 

127400 

• 

002140 

• 

000034 

132500 

002210 

000035 

0 

135600 

0 

002260 

0 

000036 

1 

140700 

1 

002330 

1 

000037 

2 

144000 

2 

002400 

2 

000040 
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147100 

3 

002450 

3 

000041 

4 

152200 

4 

002520 

4 

000042 

5 

155300 

5 

002570 

5 

000043 

6 

160400 

6 

002640 

6 

000044 

7 

163500 

7 

002710 

7 

000045 

8 

166600 

8 

002760 

8 

000046 

9 

171700 

9 

003030 

9 

000047 

C.3  MACRO  SPECIAL  CHARACTERS 


Character  Function 


form  feed 
line  feed 
carriage  return 
vertical  tab 
: 


« 

tab 

space 

# 

@ 

( 

) 

,  (comma) 

; 

+ 


* 

/ 

& 

l 

N 

'  (apostrophe) 

< 

> 

t 

t 

\ 


Source  line  terminator,  forces  a  new  listing  page 

Source  line  terminator 

Formatting  character 

Source  line  terminator 

Label  terminator 

Direct  assignment  indicator 

Register  term  indicator 

Item  terminator,  field  terminator 

Item  terminator,  field  terminator 

Immediate  expression  indicator 

Deferred  addressing  indicator 

Initial  register  indicator 

Terminal  register  indicator 

Operand  field  separator 

Comment  field  indicator 

Arithmetic  addition  operator  or  autoincrement 
indicator 

Arithmetic  subtraction  operator  or  autodecrement 
indicator 

Arithmetic  multiplication  operator 
Arithmetic  division  operator 
Logical  AND  operator 
Logical  OR  operator 
Double  ASCII  character  indicator 
Single  ASCII  character  indicator 
Assembly  location  counter 
Initial  argument  indicator 
Terminal  argument  indicator 
Universal  unary  operator 
Argument  indicator 
MACRO  numeric  argument  indicator 


C.4  ADDRESS  MODE  SYNTAX 


In  the  following  syntax  table,  n  represents  an  integer  between  0  and 
7;  R  is  a  register  expression;  E  represents  any  expression;  ER 
represents  either  a  register  expression  or  an  absolute  expression  in 
the  range  0  to  7. 

On  Register  R  Register  R  contains  the  operand. 

R  is  a  register  expression. 

In  Deferred  Register  @R  or  (R)  Register  R  contains  the  operand 

address. 
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2n  Autoincrement  (ER)+ 

Deferred 

3n  Autoincrement  @ (ER) + 

4n  Autodecrement  - (ER) 

Deferred 

5n  Autodecrement  (ER) 


Index  by  the 
Register 

6n  Specified  E(ER) 


Deferred  index 
by  the  Register 

7n  Specified  @E (ER) 

27  Immediate  Operand  #E 

37  Absolute  address  @#E 

67  Relative  address  E 

77  Deferred  relative 

address  @E 


The  contents  of  the  register 
specified  by  ER  are  incremented 
after  being  used  as  the  address 
of  the  operand. 


ER  contains  a  pointer  to  the 
address  of  the  operand.  ER  is 
incremented  after  use. 

The  contents  of  register  ER  are 
decremented  before  being  used  as 
the  address  of  the  operand. 


The  contents  of  register  ER  are 
decremented  before  being  used  as 
a  pointer  to  the  address  of  the 
operand. 


The  value  obtained  when  E  is 
combined  with  the  contents  of 
the  register  specified  (ER)  is 
the  address  of  the  operand. 


E  added  to  ER  produces  a  pointer 
to  the  address  of  the  operand. 

E  is  the  operand. 

E  is  the  operand  address. 

E  is  the  address  of  the  operand. 


E  is  a  pointer  to  the  address  of 
the  operand. 


C.5  INSTRUCTIONS 

The  tables  of  instructions  which  follow  are  grouped  according  to  the 
operands  they  take  and  according  to  the  bit  patterns  of  their 
op-codes . 

The  following  symbols  are  used  to  indicate  the  instruction  type 
format  s 

OP  Instruction  mnemonic 

R  Register  Expression 

E  Expression 

ER  Register  expression  or  expression 

OOER<«7 

AC  Floating  point  register  expression 

A  General  address  specification 
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In  the  representation  of  op-codes,  the  following  symbols  are  used: 


SS  Source  operand 

DD  Destination 

operand 

XX  8-bit  offset  to  a 

location 

R  Integer  between  0 

and  7 


Specified  by  a  6-bit 
address  mode 

Specified  by  a  6-bit 
address  mode 

Branch  instructions 


Represents  a  general 
register 


Symbols  used  in  the  description  of  instruction  operations  are: 

SE  Source  Effective  Address 

FSE  Floating  Source  Effective  Address 

DE  Destination  Effective  Address 

FDE  Floating  Destination  Effective  Address 

I  I  Absolute  Value  of 

(  )  Contents  of 

■+■  Becomes 

The  condition  codes  in  the  processor  status  word  (PS)  are  affected  by 
the  instructions;  these  condition  codes  are  represented  as  follows: 


N  Negative  bit: 

Z  Zero  bit: 

V  Overflow  bit: 

C  Carry  bit: 


Set  if  the  result  is  negative 
Set  if  the  result  is  zero 
Set  if  the  operation  caused  an 
overflow 

Set  if  the  operation  caused  a 
carry 


In  the  representation  of  the  instruction's  effect  on  the  condition 
codes,  the  following  symbols  are  used: 


0 

1 


Conditionally  set 
Not  affected 
Cleared 
Set 


To  set  conditionally  mews  to  use 
determine  the  state  of  the  code. 


the  instruction's  result  to 


Logical  operators  are  represented  by  the  following  symbols: 
1  Inclusive  OR 

(I)  Exclusive  OR 

&  AND 

—  Used  over  a  symbol  to  represent 

the  l's  complement  of  the  symbol 
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C.5.1  Double  Operand  Instructions 


Op-Code 

Mnemonic 

Stands  for 

01SSDD 

MOV 

MOVe 

11SSDD 

MOVB 

MOVe  Byte 

02SSDD 

CMP 

CoMPare 

12SSDD 

CMPB 

CoMPare  Byte 

03SSDD 

BIT 

Bit  Test 

13SSDD 

BITB 

Bit  Test  Byte 

04SSDD 

BIC 

Bit  Clear 

14SSDD 

BICB 

Bit  Clear  Byte 

05SSDD 

BIS 

Bit  Set 

I5SSDD 

BISB 

Bit  Set  Byte 

06SSDD 

ADD 

ADD 

16SSDD 

SUB 

SUB tract 

C.5.2 

Single  Operand 

Instructions 

Op- code 

Mnemonic 

Stands  for 

0050DD 

CLR 

CLeaR 

1050DD 

CLRB 

CLeaR  Byte 

0051DD 

COM 

COMplement 

1051DD 

COMB 

COMplement  Byte 

0052DD 

INC 

INCrement 

1052DD 

INCB 

INCrement  Byte 

0053DD 

DEC 

DECrement 

1053DD 

DECB 

DECrement  Byte 

0054DD 

NEG 

NEGate 

1054DD 

NEGB 

NEGate  Byte 

0055DD 

ADC 

ADd  Carry 

1055DD 

ADCB 

ADd  Carry  Byte 

0056DD 

SBC 

SuBtract  Carry 

1056DD 

SBCB 

SuBtract  Carry 
Byte 

0057DD 

TST 

TeST 

1057DD 

TSTB 

TeST  Byte 

(OP  A, A) 


Status  Word 

Condition 

Codes 


Operation 

N 

z 

V 

c 

(SE)  -*■  (DE) 

* 

* 

0 

- 

(SE)-(DE) 

* 

* 

* 

* 

(SE)  &  (DE) 

* 

* 

0 

- 

(SE)  &  (DE)  +  (DE) 

* 

* 

0 

- 

(SE)  I  (DE)  -*■  (DE) 

* 

* 

0 

- 

(SE)  +  (DE)  -*•  (DE) 

* 

* 

* 

* 

(DE)  -  (SE)  + (DE) 

* 

♦ 

* 

* 

(OP  A) 

Status  Word 

Condition 

Operation 

Codes 
N  Z 

V 

c 

0  -*■  (DE) 

0 

1 

0 

0 

(DE)  -*■  (DE) 

* 

* 

0 

1 

(DE)  +  1  (DE) 

* 

* 

* 

1 

(DE)  -  1  -»■  (DE) 

* 

* 

* 

- 

(DE)  +  1  (DE) 

* 

* 

* 

* 

(DE)  +  (C)  -*■  (DE) 

* 

* 

* 

* 

(DE)  -  (C)  -*■  (DE) 

* 

* 

* 

* 

(DE) 

* 

* 

0 

0 
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C.5.3  Rotate/Shift 


Op-Code 

Mnemonic 

Stands  for 

Operation 

Status  Word 

Condition 

Codes 

N  Z  V  C 

0060DD 

ROR 

Rotate  Right  FH" 

±.  .  .  •  ■'  .  i  . 

* 

* 

* 

* 

1060DD 

RORB 

Rotate  Right 

C 

-^-1  »  ■  1  I  1 — i — 1 — 

1 

* 

* 

* 

* 

Byte 

—0—1  '• — 

0061DD 

ROL 

Rotate  Left 

EH 

i  9 

-1 —  i  i-l.  ,  *  1  i  ,  1 

— — J 

* 

* 

* 

* 

1061DD 

ROLB 

Rotate  Left 

c 

- ooo - 1  I - 

-a--ill.il  1  ■  1 

— Even - 1 

^  .  1  i  .  1 

* 

* 

* 

* 

Byte 

t 

L 

r 

-0 — r 

0062DD 

ASR 

Arithmetic 

* 

* 

* 

* 

Shift  Right 

1  .  ■  i  '  ■  i  ■  ■ 

■  ■  ■.  IHZ3— 

1062DD 

ASRB 

Arithmetic 

* 

* 

* 

* 

Shift  Right 

dyH 

wu,'  ■ 

'-i^J  ■ 

Byte 

0063DD 

ASL 

Arithmetic 

ek 

I.  L  ,  1  .  .1  ,  ,  |  , 

»  i  ■  .0K~° 

* 

* 

* 

* 

Shift  Left 

106 3DD 

AS  LB 

Arithmetic 

□H" 

1  'dU*.  ■ 

~7  ‘  EVEN* AOONESS^  ‘  ‘  O^0 

* 

* 

* 

* 

Shift  Left 

Byte 

0001DD 

JMP 

jump 

DE  ^-(PC) 

• 

- 

- 

- 

0003DD 

SWAB 

SWAp  Bytes 

rr 

_ \ -  ; - - 

■  1  r 

* 

* 

0 

0 

The  following  instructions  are  available  on  the  PDP-11/35,40,45  as 


noted : 

Op-Code  Mnemonic 

Stands  for 

Operation 

Status  Word 

Condition 

Codes 

N  Z  V  C 

11/35,  11/40,  11/45  with  KT11 

006 5SS  MFPI 

Move  From 
Previous 
Instruction 
space 

(SE)  (TEMP) 

(SP)  -2  +  (SP) 

(TEMP)  -►  (  (SP) ) 

*  *  o  - 

11/45  with  KT11  only 

1065SS  MFPD 

Move  From 
Previous 

Data  space 

(SE)  +  (TEMP) 

(SP)  -2  -►  (SP) 

(TEMP)  -►  (  (SP) ) 

*  *  o  - 
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11/35, 

11/40,  11/45  with  KT11  . 

0066DD 

MTPI 

Move  To 
Previous 
Instruction 
space 

11/45  with  KT11  only 

1066DD 

MTPD 

Move  To 
Previous 

Data  space 

1701DD 

LDFPS 

Load  FPP 
program  status 

11/35, 

11/40,  11/45 

0067DD 

SXT 

Sign  eXTend 

11/45  with  FP11-B 

0707DD 

NEGD 

NEGate  Double 

0707DD 

NEGF 

NEGate  Floating 

1702DD 

STFPS 

STore  Floating 
Point  processor 
program  Status 

1703DD 

STST 

STore  floating 
point  processor 
STatus 

1704DD 

CLRD 

CLeaR  Double 

1704DD 

CLRF 

CLeaR  Floating 

1705DD 

TSTD 

TeST  Double 

1705DD 

TSTF 

TeST  Floating 

1706DD 

ABSD 

make  ABSolute 
Double 

1706DD 

ABSF 

make  ABSolute 
Floating 

( (SP) )  ->•  (TEMP) 
(SP+2)  -► (SP) 
(TEMP)  •+  (DE) 


(  (SP) )  -►  (TEMP) 
(SP+2)  -*■  (SP) 
(TEMP)  -*•  (DE) 

DE  FPS 


0  -*■  DE  if  N  bit 
is  clear 
-1  -*■  DE  if  N  bit 
is  set 


-  (FDE)  FDE 

-  (FDE)  FDE 


See  Chapter  7 
in  PDP-11/45 
Processor 
Handbook 


0  -*■  (FDE) 

0  -►  (FDE) 
(FDE) 

(FDE) 

|  (FDE)|  (FDE) 


|  (FDE)|  -*■  (FDE) 
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C.5.4  Operate  Instructions  (OP) 


Status  Word 
Condition 

Codes 

Op-Code 

Mnemonic 

Stands  for 

Operation 

N 

z 

V 

c 

000000 

HALT 

HALT 

The  computer  stops 
all  functions. 

- 

- 

- 

- 

000001 

WAIT 

WAIT 

The  computer  stops 
and  waits  for  an 

- 

- 

- 

- 

interrupt. 

000002 

RTI 

ReTurn  from 

The  PC  and  ST  are 

* 

* 

* 

* 

Interrupt 

popped  off  the  SP 

(Return  from 

stack : 

Trap) 

( (SP) )  +  (PC) 

(SP)  +2  -*■  (SP) 

( (SP)  )  (ST) 

(SP)  +2  -»■  (SP) 

000005 

RESET 

RESET 

Returns  all  i/o 
devices  to 
power-on  state. 

- 

- 

- 

- 

000241 

CLC 

CLear  Carry  bit 

o+c 

- 

- 

- 

0 

000261 

SEC 

SEt  Carry  bit 

1  -+c 

- 

- 

- 

1 

000242 

CLV 

CLear  overflow 

0  -+ V 

- 

- 

0 

- 

000262 

SEV 

SEt  overflow 
bit 

1  -*■  V 

- 

- 

1 

- 

000244 

CLZ 

CLear  Zero  bit 

0  z 

- 

0 

- 

- 

000264 

SEZ 

SEt  Zero  bit 

1  +z 

- 

1 

- 

- 

000250 

CLN 

CLear  Negative 
bit 

0  N 

0 

- 

- 

- 

000270 

SEN 

SEt  Negative 
bit 

1  N 

1 

- 

- 

- 

000257 

CCC 

Clear  all 

0+N 

0 

0 

0 

0 

Condition 

0  -*■  z 

Codes 

0  -+  V 

o+c 

000277 

see 

Set  all 

1  N 

1 

1 

1 

1 

Condition 

1  -*■  Z 

Codes 

1  -*•  V 

1  C 

000240 

NOP 

No  operation 
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The  following  instructions  are  available  on  the  PDP-11/45  with  FP11-B 
only: 


Op-Code  Mnemonic 
170000  CFCC 


170011  SETD 


170001  SETF 


170002  SETI 


170012  SETL 

All  11/45' s,  with  and 


Stands  for 

Operation 

Status  Word 

Condition 

Codes 

N  Z  V  C 

Copy  Floating 
Condition  Code 

Copy  FPP 
condition  codes 
into  CPU  condi¬ 
tion  codes. 

*  * 

*  * 

SET  Double 

floating 

mode 

FPP  set  to 

double 

precision 

—  — 

—  — 

SET  Floating 
mode 

FPP  set  to 
single 
precision 
mode 

SET  Integer 
mode 

FPP  set  for 
integer  data 
(16  bits) 

—  — 

—  — 

SET  Long 
integer  mode 

without  FP11-B 

FPP  set  for 
long  integer 
data  (32  bits) 

000006  RTT 


ReTurn  from 
inTerrupt 


Same  as  RTI 
instruction  but 
inhibits  trace 
trap 


C.5.5 


Trap  Instructions  (OP 
*  (OP 


or  OP  e  where  0<=E<®377 (8) ) 
(only) ) 


Op-Code  Mnemonic 


Stands  for 


*000003  BPT 


Breakpoint 

Trap 


*000004  IOT 


Input  Output 
Trap 


Operation 


Trap  to 
location  14. 
This  is  used 
to  call  ODT. 

Trap  to 
location  20. 
This  is  used 
to  call  IOX. 


Status  Word 

Condition 

Codes 

N  Z  V  C 


*  *  *  * 


*  *  *  * 
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104000-  EMT  EMulator 

104377  Trap 


104400-  TRAP  TRAP 

104777 


Trap  to  *  *  *  * 

location  30, 

This  is  used 
to  call  system 
programs . 

Trap  to  *  *  *  * 

location  34. 

This  is  used 
to  call  any 
routine  desired 
by  the  programmer. 


C.5.6  Branch  Instructions  OP  E 

(where  -128 (decimal) < (E-.-2) /2<127 (decimal) ) 

Condition  to  be 
met  if  branch  is 


Op-Code 

Mnemonic 

Stands  for 

to  occur 

0004XX 

BR 

B Ranch  always 

0010XX 

BNE 

Branch  if  Not  Equal  (to  zero) 

z=o 

0014XX 

BEQ 

Branch  if  EQual  (to  zero) 

Z=»l 

0020XX 

BGE 

Branch  if  Greater  than  or 

Equal  (to  zero) 

n©  v=o 

0024XX 

BLT 

Branch  if  Less  Them  (zero) 

n©  v  =  i 

0030XX 

BGT 

Branch  if  Greater  Them 
( zero) 

Z 1  (N  ©  V)  =0 

0034XX 

BLE 

Branch  if  Less  than  or 

Equal  (to  zero) 

Z !  (N  ©  V)  =1 

1000XX 

BPL 

Branch  if  PLus 

N=0 

1004XX 

BMI 

Branch  if  Minus 

N«1 

1010XX 

BHI 

Bremch  if  Higher 

C©  Z-0 

1014XX 

BLOS 

Bremch  if  LOwer  or  Seune 

C!Z=1 

1020XX 

BVC 

Bremch  if  overflow  Clear 

V=0 

1024XX 

BVS 

Bremch  if  overflow  Set 

V»1 

1030XX 

BCC  (or 
BHIS) 

Bremch  if  Carry  Clear 
(or  Branch  if  High  or  Same) 

c=o 

1034XX 

BCS  (or 
BLO) 

Branch  if  Carry  Set  (or 

Bremch  if  LOw) 
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C.5.7  Register  Destination  (OP  ER,A) 


Op-Code  Mnemonic  Stands  for 


Operation 


Status  Word 

Condition 

Codes 

N  Z  V  C 


004RDD  JSR  Jump  to 

Sub Routine 


Push  register 
on  the  SP  stack, 
put  the  PC  in 
the  registers 


DE  TEMP  (TEMP= 
temporary  storage 
register  internal 
to  processor.) 


(SP)  -2  -►  SP 
(REG)  (SP) 
(PC)  +  REG 
(TEMP)  -v  PC 


The  following  instruction  is  available  only  on  the  11/35, 
11/45: 

074RDD  XOR  exclusive  OR  (R)  (?)  (DE)  (DE)  *  * 


11/40, 


C.5.8  Register-Offset  (OP  R,E) 

The  following  instruction  is  available  only  on  the  PDP-11/35,  11/40, 


11/45: 

Op-Code 

Mnemonic 

Stands  for 

Operation 

N 

Z 

V 

c 

077RDD 

SOB 

Subtract  One 

(R)-l^(R) 

— 

mm 

• 

mm 

and  Branch 

(PC) — (2*DE)  +  (PC) 

C.5.9  Subroutine  Return  (OP  ER) 

Op-Code 

Mnemonic 

Stands  for 

Operation 

N 

Z 

V 

C 

00020R 

RTS 

ReTurn  from 

Put  register 

— 

mm 

• 

— 

Subroutine 

in  PC  and  pop 

old  contents  from 
SP  stack  into 
register. 
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C.5.10  Source-Register  (OP  A,R) 

The  following  instructions  are  available  on  the  11/35,  11/40,  11/45 


only: 

Op-Code 

Mnemonic 

Stands  for 

Operation 

Status  Word 
Floating 
Condition 
Codes 

N  Z  V  C 

071RSS 

DIV 

Divide 

(R)  ,  (Rl  1)  / (SRC)  +  (R) 

9  (Rl 1) 

*  *  *  * 

070RSS 

MUL 

MULtiply 

(R) * (SRC)  -  (R) , (RI 1) 

*  *  *  * 

072RSS 

ASH 

Arithmetic 

SHift 

R  is  shifted 
according  to 
low-order  6- bits 
of  source 

CL> . ~ . . . 

or 

EH  i  .  ■  i  .  .  i'r~.  i  .  .  i  .  .  K 

073RSS 

ASHC 

Arithmetic 

SHift 

Combined 

R,RVL  are  shifted 
according  to  low- 
order  6  bits  of 
source 

*  *  *  * 

dL»J  ■  -  1  '  1  '  1  ‘  F1 
i1.  ...  . . i-n 

or 

-n-r,  .  ,  .  .  t~tt  i 

■"  i*i  .  .  i  .  .  'i  .  i  .  .  i .  n~ 


C.5.11  Floating-Point  Source  Double  Register  (OP  A, AC) 


The  following  instructions  are  available  on  the  PDP-11/45  with  FP11-B 
only: 


Status  Word 
Floating 
Condition 
Codes 

Op-Code  Mnemonic  Stands  for  Operation  FN  FZ  FV  FC 


172 (AC)SS  ADDD  ADD  Double  (FSE)  +(AC)  -*•  (AC)  *  *  *  0 
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172 (AC)SS  ADDF 

ADD  Floating 

(FSE)  +  (AC)  (AC) 

* 

173(AC+4)SS 

CMPD 

CoMPare 

Double 

(FSE)  - (AC) 

* 

173(AC+4)SS 

CMPF 

CoMPare 

Floating 

(FSE)  -  (AC) 

* 

174 (AC+4) SS 

DIVD 

Divide 

Double 

(AC)  / (FSE)  -*■  (AC) 

* 

174 (AC+4 )SS 

DIVF 

Divide 

Floating 

(AC)  /  (FSE)  -*■  (AC) 

* 

177 (AC+4 )SS 

LDCDF 

Load)  and  Con¬ 
vert  from 
Double  to 
Floating 

(FSE)  +  (AC) 

* 

177 (AC+4) SS 

LDCFD 

LoaD  and  Con¬ 
vert  from 
Floating  to 
Double 

(FSE)  -*■  (AC) 

* 

172 (AC+4) SS 

LDD 

LoaD  Double 

(FSE)-*-  (AC) 

* 

172 (AC+4) SS 

LDF 

LoaD  Floating 

(FSE)  -*■  (AC) 

* 

171 (AC+4) SS 

MODD 

Multiply  and 

integenze 

double 

(AC)  *  (FSE)  -*■  (AC)  ,  (AC1) 

* 

171 (AC+4) SS 

MODF 

Multiply  and 
integer! ze 
floating¬ 
point 

(AC)  *  (FSE)  (AC) 

* 

171 (AC) SS  MULD 

MULtiply 

Double 

(AC)  *  (FSE)  -»■  (AC) 

* 

171 (AC) SS  MULF 

MULtiply 

Floating 

(AC)  *  (FSE)  -+  (AC) 

* 

173 (AC)SS  SUBD 

SUBtract 

Double 

(FSE)  —  (AC)  •+  (AC) 

* 

173 (AC) SS  SUBF 

SUBtract 

Floating 

(FSE)  —  (AC)  •+•  (AC) 

* 

*  * 

*  0 


*  0 


*  * 


*  * 


*  * 


*  * 

*  0 

*  0 


*  * 


*  * 


*  * 


*  * 


*  * 


*  * 


0 

0 


0 


0 


0 


0 


0 


0 

0 


* 


0 


0 

0 

0 

0 


C-16 


MACRO  Assembler ,  Instruction,  and  Character  Code  Summaries 


C.5.12  Source-Double  Register  (OP  A, AC) 

The  following  instructions  are  available  on  the  PDP-11/45  with  FPll-B 
only: 


Status  Word 
Condition  Codes 


Op- Code 

Mnemonic 

Stands  for  Operation 

FN 

FZ 

FV 

FC 

177 (AC)SS 

LDCID 

LoaD  and  Con-  (SE)  -*■  (AC) 
vert  Integer 
to  Double 

* 

* 

* 

0 

177 (AC)SS 

LDCIF 

LoaD  and  Con-  (SE)  ->•  (AC) 
vert  Integer 
to  Floating 

* 

* 

* 

0 

177 (AC)SS 

LDCLD 

LoaD  and  Con-  (SE)  ■+  (AC) 
vert  Long 
integer  to 

Double 

* 

* 

* 

0 

177 (AC) SS 

LDCLF 

LoaD  and  Con-  (SE)  (AC) 
vert  Long  In¬ 
teger  to 

Floating 

* 

* 

* 

0 

176 (AC+4) SS 

LDEXP 

LoaD  EXPonent  (SE)+200  ^ (AC  EXP) 

* 

* 

0 

0 

C.5.13  Double  Register-Destination  (OP  AC, A) 

The  following  instructions  are  available  on  the  PDP-11/45  with  FPll-B 
only: 


Op-Code  Mnemonic  Stands  for  Operation 


Status  Word 
Condition  Codes 
FN  FZ  FV  FC 


176 (AC) DD 

STCFD 

STore,  Con¬ 
vert  from 
Floating  to 
Double 

(AC)  (FDE) 

176 (AC) DD  STCDF 

175 (AC+4) DD 

STore,  Con¬ 
vert  from 
Double  to 
Floating 

(AC)  -►  (FDE) 

STCDI(l) 

STore,  Con¬ 
vert  from 
Double  to 
Integer 

(AC)  -*■  (FDE) 

*  *  *  o 


*  *  *  0 


(1) These  instructions  set  both  the  floating-point  and  processor 
condition  codes  as  indicated. 
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175 (AC+4) DD 

STCDL(l)  STore,  Con-  (AC)  +  (FDE) 
vert  from 
Double  to 
Long  integer 


175 (AC+4) DD 

STCFI(l) 

STore,  Con-  (AC)  (FDE) 

vert  from 

Floating  to 

Integer 

*  *  0  * 


174 (AC+4) DD 

STCFL(l)  STore,  Con-  (AC)  -*■  (FDE)  *  *  0  * 

vert  from 
Floating  to 
Long  integer 


174 (AC) DD  STD 
174 (AC) DD  STF 


STore  Double  (AC)  -*■  (FDE) 

STore  (AC)  (FDE) 

Floating 


175 (AC) DD  STEXP(l)  STore 

EXPonent 


(AC  EXP) -200  ->■  (DE)  * 


0 


0 


C.5.14  Number 


The  following  instruction  is  available  on  the  11/35,  11/40,  11/45 

only: 


Op-Code 


Mnemonic  Stands  for 


Operation 


Status  Word 
Condition  Codes 
N  Z  V  C 


0064NN  MARK  MARK 


Stack  cleanup  on 
return  from  sub¬ 
routine. 


C.5.15  Priority 

The  following  instruction  is  available  on  the  PDP-11/45  only: 

Status  Word 
Condition 
Codes 

Operations  N  Z  V  C 


(X)  +  (PS) 
(bits  7-5) 


Op-Code  Mnemonic  Stands  for 

00023N  SPL  Set  Priority 

Level 


the  floating-point  and  processor 


(1) These  instructions  set  both 
condition  codes  as  indicated. 
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C.6  ASSEMBLER  DIRECTIVES 

Described  in 

and  Character  Code  Summaries 

Form 

Manual  Section 

Operation 

• 

5. 5. 3. 3 

A  single  quote  character  (apostrophe) 
followed  by  one  ASCII  character 
generates  a  word  containing  the  7-bit 
ASCII  representation  of  the  character 
in  the  low-order  byte  and  zero  in  the 
high-order  byte. 

N 

5. 5. 3. 3 

A  double  quote  character  followed  by 
two  ASCII  characters  generates  a  word 
containing  the  7-bit  ASCII 
representation  of  the  two  characters. 

\ 

5. 6. 3. 3 

A  backslash  preceding  an  argument 
causes  the  number  to  be  treated  in  the 
current  radix. 

tBn 

5. 5. 4. 2 

Temporary  radix  control;  causes  the 
number  n  to  be  treated  as  a  binary 
number. 

tCn 

5. 5. 6. 2 

Creates  a  word  containing  the  one's 
complement  of  n. 

tDn 

5. 5. 4. 2 

Temporary  radix  control;  causes  the 
number  n  to  be  treated  as  a  decimal 
number. 

tFn 

5. 5. 6. 2 

Creates  a  one-word  floating  point 

quantity  to  represent  n. 

tOn 

5. 5. 4. 2 

Temporary  radix  control;  causes  the 
number  n  to  be  treated  as  an  octal 
number. 

.ASCII  string 

5. 5. 3. 4 

Generates  a  block  of  data  containing 
the  ASCII  equivalent  of  the  character 
string  (enclosed  in  delimiting 
characters)  one  character  per  byte. 

.ASCIZ  string 

5. 5. 3. 5 

Generates  a  block  of  data  containing 
the  ASCII  equivalent  of  the  character 
string  (enclosed  in  delimiting 
characters)  one  character  per  byte 
with  a  zero  byte  following  the 
specified  string. 

.ASECT 

5.5.9 

Begin  or  resume  absolute  section. 

. BLKB  exp 

5. 5. 5. 3 

Reserves  a  block  of  storage  space  exp 
bytes  long. 

•  BLKW  exp 

5. 5. 5. 3 

Reserves  a  block  of  storage  space  exp 
words  long. 
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.BYTE  expl, 
exp2 , . . . 

5. 5. 3.1 

Generates  successive  bytes  of  data 
containing  the  octal  equivalent  of  the 
expression (s)  specified. 

.CSECT  symbol 

5.5.9 

Begins  or  resumes  named  or  unnamed 

relocatable  section. 

.DSABL  arg 

5.5.2 

Disables  the  assembler  function 

specified  by  the  argument. 

. ENABL  arg 

5.5.2 

Provides  the  assembler  function 

specified  by  the  argument. 

.END 

.END  exp 

5. 5. 7.1 

Indicates  the  physical  end  of  the 
source  program.  An  optional  argument 
specifies  the  transfer  address. 

.ENDC 

5.5.11 

Indicates  the  end  of  a  condition 

block. 

.ENDM 

.ENDM  symbol 

5. 6. 1.2 

Indicates  the  end  of  the  current 
repeat  block,  indefinite  repeat  block, 
or  macro.  The  optional  symbol,  if 
used,  must  be  identical  to  the  macro 
name. 

.EOT 

5. 5. 7. 2 

Ignored.  Indicates  End-of-Tape  which 
is  detected  automatically  by  the 
hardware . 

.ERROR  exp, string 

5.6.5 

Causes  a  text  string  to  be  output  to 
the  listing  containing  the  optional 
expression  specified  and  the  indicated 
text  string.  The  line  will  be  flagged 
with  the  "P"  error  code. 

.EVEN 

5. 5. 5.1 

Ensures  that  the  assembly  location 
counter  contains  an  even  address  by 
adding  1  if  it  is  odd. 

.FLT2  argl, 
arg2 ,  *  « . 

5. 5. 6.1 

Generates  successive  two-word  float¬ 
ing  point  equivalents  for  the 
floating-point  numbers  specified  as 
arguments . 

.FLT4  argl, 
arg2 , . . . 

5. 5. 6.1 

Generates  successive  four-word  float¬ 
ing  point  equivalents  for  the 
floating-point  numbers  specified  as 
arguments . 

. GLOBL  syml, 
sym2  , . . . 

5.5.10 

Defines  the  symbol (s)  specified  as 

global  symbol (s). 

. I DENT  symbol 

5. 5. 1.5 

Provides  a  means  of  labeling  the 
object  module  produced  as  a  result  of 
assembly.  This  directive  is  not 
supported  by  RT-11,  but  is  included 
for  compatibility  with  other  systems. 

.IF  cond, 
arguments 

5.5.11 

Begins  a  conditional  block  of  source 
code  which  is  included  in  the  assembly 
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•IFF  5.5.11,1 


•IFT  5.5.11.1 


.IFTF  5.5.11.1 


•IIF  cond,arg,  5.5.11.2 
statement 


•IRP  sym,  5.6.6 

<argl,arg2,...> 


. IRPC  sym, string  5.6.6 


.LIMIT  5.5.8 

.LIST  5. 5. 1.1 

.LIST  arg 


.MACRO  sym,argl,  5. 6. 1.1 
argl , . . . 

.MCALL  5.6.8 

.MEXIT  5. 6. 1.3 


only  if  the  stated  condition  is  met 
with  respect  to  the  argument (s) 
specified. 

Appears  only  within  a  conditional 
block  and  indicates  the  beginning  of  a 
section  of  code  to  be  assembled  if  the 
condition  tested  false. 

Appears  only  within  a  conditional 
block  and  indicates  the  beginning  of  a 
section  of  code  to  be  assembled  if  the 
condition  tested  true. 

Appears  only  within  a  conditional 
block  and  indicates  the  beginning  of  a 
section  of  code  to  be  unconditionally 
assembled. 

Acts  as  a  one-line  conditional  block 
where  the  condition  is  tested  for  the 
argument  specified.  The  statement  is 
assembled  only  if  the  condition  tests 
true. 

Indicates  the  beginning  of  an  indef¬ 
inite  repeat  block  in  which  the 
symbol  specified  is  replaced  with 
successive  elements  of  the  real 
argument  list  (which  is  enclosed  in 
angle  brackets) . 

Indicates  the  beginning  of  an 
indefinite  repeat  block  in  which  the 
symbol  specified  takes  on  the  value  of 
successive  characters  in  the  character 
string. 

Reserves  two  words  into  which  the 
Linker  inserts  the  low  and  high 
addresses  of  the  relocated  code. 

Without  an  argument,  .LIST  increments 
the  listing  level  count  by  1.  With  an 
argument,  .LIST  does  not  alter  the 
listing  level  count  but  formats  the 
assembly  listing  according  to  the 
argument  specified. 

Indicates  the  start  of  a  macro  with 
the  specified  name  containing  the 
dummy  arguments  specified. 

Used  to  specify  the  names  of  all 
system  macro  definitions  not  defined 
in  the  current  program  but  required  by 
the  program. 

Causes  an  exit  from  the  current  macro 
or  indefinite  repeat  block. 
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.NARG  symbol  5.6.4 

.NCHR  sym,<string> 5.6 .4 

•NLIST  5. 5. 1.1 

.NLIST  arg 

.NTYPE  symbol, arg  5.6.4 

.ODD  5. 5. 5. 2 

.PAGE  5. 5. 1.6 

.PRINT  exp, string  5.6.5 

.RADIX  n  5. 5. 4.1 

. RAD50  string  5. 5. 3. 6 

. REPT  exp  5.6.7 

. SBTTL  string  5. 5. 1.4 

.TITLE  string  5. 5. 1.3 


Appears  only  within  a  macro  definition 
and  equates  the  specified  symbol  to 
the  number  of  arguments  in  the  macro 
call  currently  being  expanded . 

Can  appear  anywhere  in  a  source 
program;  equates  the  symbol  specified 
to  the  number  of  characters  in  the 
string  (enclosed  in  delimiting 
characters) . 

Without  an  argument,  .NLIST  decrements 
the  listing  level  count  by  1.  With  an 
argument,  .NLIST  deletes  the  portion 
of  the  listing  indicated  by  the 
argument. 

Appears  only  in  a  macro  definition  and 
equates  the  low-order  six  bits  of  the 
symbol  specified  to  the  six-bit 
addressing  mode  of  the  argument. 

Ensures  that  the  assembly  location 
counter  contains  an  odd  address  by 
adding  1  if  it  is  even. 

Causes  the  assembly  listing  to  skip  to 
the  top  of  the  next  page. 

Causes  a  text  string  to  be  output  to 
the  listing  containing  the  optional 
expression  specified  and  the  indicated 
text  string. 

Alters  the  current  program  radix  to  n, 
where  n  can  be  2,  4,  8,  or  10. 

Generates  a  block  of  data  containing 
the  Radix-50  equivalent  of  the 
character  string  (enclosed  in 
delimiting  characters) . 

Begins  a  repeat  block.  Causes  the 
section  of  code  up  to  the  next  .ENDM 
or  .ENDR  to  be  repeated  exp  times. 

Causes  the  string  to  be  printed  as 
part  of  the  assembly  listing  page 
header.  The  string  part  of  each 
.SBTTL  directive  is  collected  into  a 
table  of  contents  at  the  beginning  of 
the  assembly  listing. 

Assigns  the  first  symbolic  name  in  the 
string  to  the  object  module  and  causes 
the  string  to  appear  on  each  page  of 
the  assembly  listing.  One  .TITLE 
directive  should  be  issued  per 
program. 
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.WORD  expl,  5. 5. 3. 2 

exp2 , . . . 


C.7  MACRO/CREP  SWITCHES 


Generates  successive  words  of  data 
containing  the  octal  equivalent  of  the 
expression (s)  specified. 


C.7.1  Listing  Control  Switches 
Switch  Meaning 

/L:arg  These  switches  are  used  to  control  listing  output. 
/N:arg  Arguments  which  are  valid  for  either  switch  include: 


Arg  Controls  Listing  of: 


SEQ 

LOC 

BIN 

BEX 

SRC 

COM 

MD 

MC 

ME 

MEB 

CND 

LD 

TOC 

TTM 

SYM 

<no  arg> 


Source  line  sequence  numbers 
Location  counter 
Generated  binary  code 
Binary  extensions 
Source  code 
Comments 

Macro  definitions  and  repeat  range  definitions 

Macro  calls  and  repeat  range  expansions 

Macro  expansions 

Macro  expansion  binary  code 

Unsatisfied  conditions  and  all  .IF 

and  .ENDC  statements. 

Listing  directives  having  no  arguments 
Table  of  contents 
Listing  output  format 
Symbol  table 

/N  with  no  argument  causes  only  table  of  contents, 
symbol  table,  and  error  listings  to  be  produced. 


/L  with  no  argument  causes  .LIST  and  .NLIST 
directives  without  arguments  which  appear  in  the 
source  program  to  be  ignored. 

C.7. 2  Function  Control  Switches 


Switch  Meaning 

/D:arg  These  switches  are  used  to  enable  or  disable  certain 
/E:arg  functions  in  source  input  files.  Valid  arguments 

include : 


Arg  Enables  or  Disables ; 


ABS 

AMA 

CDR 

FPT 

LC 

LSB 

PNC 


Absolute  binary  output 

Assembly  of  all  absolute  addresses  as  relative 
addresses 

Source  columns  73  and  greater  to  be  treated  as 
comments 

Floating  point  truncation 
Accepts  lower  case  ASCII  input 
Local  symbol  block 
Binary  output 
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C.7.3  CREF  Switches 


Switch 

Produces  Cross-Reference  of: 

/C:S 

/C:R 

/CsM 

/C:P 

/CsC 

User-defined  symbols 
Register  symbols 

MACRO  symbolic  names 
Permanent  symbols 
Control  sections 

/C:E  Error  codes 

/C: <no  arg>  Equivalent  to  /CsSsMsE 


APPENDIX  D 
SYSTEM  MACRO  PILE 


The  following  is  a  listing  of  the  system  macro  library 
This  file  is  stored  on  the  system  device ,  and  used  by 
expands  the  programmed  requests  discussed  in  Chapter  9. 


etc  assumes  NO  responsibility  FOR 

THE  use  OR  RELIABILITY  OF  ITS 
SOFTWARE  ON  EQUIPMENT  WHICH  IS  NOT 
SUPPLIED  BY  DEC. 


SyShAC,SML--SYSTEM  MACRO  LIBRARY 
FOR  RTU  V2 , 

OEC.ll-ORSYA-A-LA 

COPYRISHT  1974 

oisital  equipment  corporation 

MaYNARU,  MASSACHUSETTS  01754 
EF 


•  MACRO  .  •  V2 .  * 

• MC ALL  •••CMl».,,CM2».,»CMJ,.,.CM4 
...V8*l 

.ENQM 


•macro  .••Chi  .area, .code, .chan 

•IF  NB  .AREA 

MOV 

MOV 

•  ENOC 

, IlF  NB  < . CHAN» ,  MQVB 


,  ENQM 


•  ARE  A , %0 

#,coot*AO4a0, (B) 

•CHAN, (0) 


SYSMAC.SML. 
MACRO  when  it 


System  Macro  File 


.MACHO  • • • CM2  .ARC, .OFFSET, .INS 
,  I  If  N(J  SIRS*,  MOV 

, I IF  NS  BMT 

,ENDM 


,  ARG, .OFFSET (S) 
a0378 


.MACRO  ...CM3  ,CHAN,.COOfe 

MOV 

.HF  NS  4, CHAN*,  BISS 

EMT 

.ENOM 


».COOE*aQ400,X0 

, CM AN , %0 
•  0374 


.MACRO  «..Cm4  « ARE A , , CM AN , , BUF F , , RCNT , . BLR « » CRT N , , CODE 
,,.c«i  «.area»,«.code>»<.chan> 

...CM2  < , BLR* » 2 . 

...CM2  < . SUF F* ,  4 , 

,,.C«2  <.WCNTf,6. 

,,.C«2  4.CRTN*,8,,X 
.ENOM 


.MACRO  ,CUFn  .AREA, .ADO, .NUM 
...CMi  <. AREA*, 13, 

...CM2  4.ADD>,2. 

,.,C«2  4 .  NUM* , 4 ,  |  X 

.enqm 

.MACRO  .CHAIN 
...CM3  ,8. 

.ENOM 

.MACRO  .CmCqFY  .ARtA, .CHAN, .OCHAN 
...CHI  4. AREA*, 1 1. ,4. CHAN* 

...CM2  4.0CMAn*.2.,X 
.ENOM 


.MACRO  .CNTXSW  .area,, add 

.  .  .  CM  I  4,  AREA*, 27, 

. . .CM2  4 . AOD*  ,  2 . , X 
.ENQM 

.MACRO  ,CMRT  .AREA, ,10, .time 
. . . CM  1  4, AREA*, 19, 

...CM2  4 , 10* , 2 . 


IF  B  .TIME 

Ct« 

4,  (0) 

IFF 

MOV 

.TIME, 4.  (0) 

ENOC 

feM  T 

40378 

ENOM 

macro  .close  .cman 

IF  NoF  ...V2 

6MT 

aO<180*,CMAN> 

IFF 

...CM3  4.CMAN*,6. 

,£NOC 

.ENOM 
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, MACRO  .CSIGEN  .DEVSPCi .DEFEXT 

CSTRING 

MOV 

.DEVSPCi "(6.) 

MOV 

. DEFEXT, • C6. 3 

,IF  B  .CSTRING 

CLP 

•  (6, ) 

,  IPF 

MOV 

.CSTRING ,"(6.3 

,ENDC 

EMT 

*0344 

,  ENOM 

,MAC«0  .C3I3PC  , QUTSPC » .DEFEXT 

, .CSTRING 

MOV 

.OUTSPC, " (8, ) 

MOV 

.DEFEXT, "(8.) 

IF  B  .CSTRING 

CLR 

•18.) 

IFF 

MOV 

.CSTRING, -(6.) 

ENOC 

EMT 

*0349 

ENOM 

,  MACRO  , C8T AT  .AREA, .CHAN, ,AQO 

#  •  CM  1  «.AREA»,23.X.CHAN» 

..CM2  4,ADD»,2.,X 

,ENO« 

{ MACRO  .DATE 

MOV 

##94»  X0 

MOV 

*0282(0) ,X0 

ENOM 

MACRO  .DELETE  .AREA, .CHAN, .DEVBL*. .SPF 

IF  NOP  . . .  V2 

.IIP  nb  M.CHAN>  MOV 

.CHAN, 

tMT 

*04 , ARE A> 

IFF 

..CM1  <.AREA>,0,«,CHAN> 

..CM2  «.0£VBLK>,2. 

.IF  ti  ,SPF 

clr 

4.(0) 

.Iff 

MOV 

. SPF , 4 . (0) 

.ENUC 

EMT 

*0379 

ENOC 

ENOM 

macro  .device  .area, .add 

.  . CM I  «.  AREA*, 12, 

..CM2  <.A00»i2.,X 

ENOM 

MACRO  .DSTATU3  , RETSPC , , ON AME 

I IF  NB  < .  DNAME» ,  MOV 

. ONAME , X0 

MOV 

.RETSPC, -(8.) 

EMT 

*0342 

.ENQM 
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.MACHO  .enter  .area, 

.CHAN, , 

OEVBUK, .UEN, ,SRF 

.IF  NOF  . . .  V2 

MOV 

, chan , XU 

•IF  0  .ObVBlK 

CLR 

•(6,3 

.IFF 

MOV 

,DEV0UK,-Ca.) 

.ENOC 

EMT 

*O<40+ , ARE A> 

.iff 

.  .  . CM 1  < , ARE A> , 2  .  ,  <  , 

CHAN> 

...CM2  «.DEV0LK>«2. 
.IF  NB  .UEN 

MOV 

.UEN, 4, (0) 

.IFF 

CUR 

4.(0) 

.ENOC 

.IF  NB  . SPF 

MOV 

« SPF , 6 . (0) 

.IFF 

CUR 

6.  (0) 

.ENOC 

EMT 

*0375 

.ENOC 

i  ENOC 
,CN0« 


.MACHO  .EXIT 
,EN0M 


EMT 


.MACRO  .FETCH  ,ADD,.DNAME 
•  I IK  Nd  < . ON AME> , 


,£nom 


.MACHO  .ST1M  , ARE A ,  ,  AOO 

* • AREA> , 1 7 » 

...CM2  <,A0D».2.,X 

.ENOM 

.MACHO  .ttTJB  ,  AKE  A  ,  ,  ADD 

.  .  • CM J  <,AR£A*>16, 

,..C«2  < . AOD* ,  2 . »  X 
,EN[)M 


.MACRO  ,MtRR 
•  •  •  CM3  *5. 

.ENOM 

.MACHO  . HrEsET 

.ENOM 


EMT 


*0350 


MOV  .ONAME.X0 
MOV  . ADD#  » (8,  ) 
EMT  *0343 


*0357 
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,MAC«0 

, inTen 

.PHIO#. 

PIC 

.IF  Nb 

.PIC 

MOV 

M*0S4,.(S.  J 

JSH 

3.'»(6.)* 

.IPF 

JS« 

5,,#*0&4 

.ENOC 

.WORD 

*C«.PRIQ*32.n224, 

.ENDM 

.MACRO 

.LOCK 

EMT  *0346 

.INOM 

.MACHO 

.LOOKUP 

.ARC A. ,ChAN, .OEV0LK. ,SpF 

.IF  NOF 

. . .  V2 

. I  IF  Nb  <.CHaN>, 

MOV 

,CHAN,X0 

.iff 

EMT 

*0429*. AREA* 

...CMl  <,ARfcA»,i,<, 
...CM2  <.DEVBLK>,2, 
.IF  b  ,  §PF 

CHAN> 

.IFF 

CLR 

4,(2) 

.Enuc 

MOV 

, SPF , 4 . (9) 

,EN0C 

.ENDM 

tMT 

*0373 

.MACHO  . MRKT  .  AREA  , 
...CMl  « .ARE** ,18. 
...CM2  <.11ME>,2. 
...CM2  <.CRTN>,4. 
...CM2  *.I0»i6.,X 

,EMOM 

.MACHO  .MwAJT 
...CM3  #®. 

,EN0M 

.MACHO  .PRINT  .ADD 

.TIME..CRTN 

'.IQ 

,  HP  NB  <. ADO>, 

MOV 

•  ADD«  X0 

.ENDM 

EMT 

*0391 

.MACHO  .PROTECT  .AREA, .ADO 
...CMl  «. AREA*, gb, 

...CM2  <»A0D>,2. , x 
,ENOM 

.macro  .purge  .chan 

...CM3  «,CMAN>,3, 
,ENOM 

.MACHO  . 09ET  ,QAOD, 

.QLEN 

•  I IF  Nb  <.0LEN», 

MQ  VB 

.QLEN, X0 

MOV 

,QAD0,-(6.) 

•  EN0M 

EMT 

*0393 
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.MACHO  .RCTRLO 
.ENQM 


EMT  AQ355 


.MACHO  .RCVU  .ArEA, .BUFF# .WCNT 

, ..CM4  <#aREA>, ,<.BUFF>,<.WCnT>, ,#1,22. 

.ENOM 


.macho  .rcvdc  .area, .buff, .wcnt, .crtn 
,,,CM4  «.  AREA*,  ,«,BuFF>,«,WCNT>,  ,«,CRTN>,22. 
,ENDM 


.MACHO  .KCVOW  ,  AREA,  , BUFF  ,  ,'AiCNT 

...C^A  <.aREA»#,«.BUFF>,<.WCNT>,,#0,22. 
.  ENOM 


.macho  .head  .AREA# 

.IF  NDF  .  .  <  V2 
,  I  IF  NB  <.WCNT>» 


.IFF 


CHAN,  .BUFF,  .WCNT#  ,B|.K 

MOV  ,WCNT,X0 

MOV  H 1 , ■  (6  .  ) 

MOV  ,BUFF,«C6.) 

MOV  .CHAN, » (8, ) 

feMT  aO«200A, AREA* 


, ,.CM4  <,AREA>,«,CHaNW,«.BUPF>,«,WCNT>,«,8LK*,W1,S 


.endc 

.ENOM 


.MACHO  .REAOC  .AREA, 
.IF  NDF  ...V2 

.CHAN, .BUFF 

,  .WCNT, ,C«TN, .BUK 

. IlF  Ns  a,CRTN», 

MOV 

,CRTN,X0 

MOV 

.WCNT, -(8.) 

MOV 

.BUFF, -(6.) 

MOV 

.CHAN, .(8.) 

EMT 

AO4200+.AREA* 

.X?F 

,  ,,CM4  «.AREA»,<,CNANw,«.8UFP>,  < ,  WCNT* ,  «e , BLK> ,  «.CRTN»,8. 


,ENOC 

.ENOM 


.MACHO  .RtAOW  ,  ARE A , , CH AN , , BUFF 
.IF  NOK  . . . V2 

.IIP  NB  <,WCNT>,  MOV 

CUR 

MOV 

MOV 

EMT 


,.wcnT,.buk 

.  WCNT , X0 
•  16.) 

.BUFF, -(6.) 
.CHAN, •(6.3 
aQ«200A  .  AR£a> 


.IFF 

, ,  ,CM4  <,AREA>,<.CHAN»,«.BUFF>,<.hCNTi»,<,BUA>,»0,8. 
.ENDC 

,  enqm 


.MACHO  .RteOEF 

R0«X0 

R1«XV 

R2-X2 

R3»Xi 

R4«X4 

RS«X3 

$P*X« 

PC*X7 

.ENOM 
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.MACHO  .RELEASE  , DtvBLK 
•  1 1»-  Nb  <.UEVBLK»,  MOV 

CI.H 

Emt 

,ENQM 


.OEVbLK.Xe 

•(6.) 

*0343 


,MAC«0  .HfcNAME  .AREA#  .CrtAN,  .0EV8I.K 
.IF  HOF  ,  ,,v2 

,  I IF  Mb  «.CHAN>,  MOV  .CHAN. %0 

EMT  *0< l 00+ , ARE A> 

.iff 

...CMl  <,AREA»,  A, ,<,CHAN» 

...CM2  < . UEVBLK»  # 2  <  #  X 

.ENOC 

.ENOM 


.MACHO  .REOPEN  .  AREA  »  .ChAN,  ,C8LK 
.IF  NOF  ...V2 

. I IF  Nb  «.CMAN>,  MOV  .CMAN.X0 

EMT  aO«140+.AREA> 

.iff 

...CMl  «. AREA*, CHAN* 

...CM2  <  .  Cbl.H»  #  2  .  .  X 
.ENOC 
.  ENOM 


.macro  .SAVE5TAT  .AREA, .CHAN, ,C8LK 
.IF  NOF  . . . V2 

, I IF  N8  «,CHAN>,  MOV  .CHAN. X0 

emt  *o«i20+,area> 

.IFF 

...CMl  <.AREA>.8i,«,CMAM» 

...CM2  «.CbLK>i2.#X 

.ENOC 

.ENOM 

.macro  .R8UM 


...CM3  #2. 

.  ENpM 

.MACHO  .SDAT  .AREA#, BUFF#, *CNT 
, . .CM4  «,area>, , «.BUFF>, «,WCNT>, #«l,2l. 

.ENOM 

.MACHO  .SOATC  . ARE A , , BUFF , , WQNT , , CRTN 
...CM4  «.AREA>, ,<,BUFF>,<.WCNT>, #«,CRTN>#21. 

,ENQM 

.MACHO  .SDATW  . ARE A , , BUFF , . WCNT 
...CM4  «.AREA*, ,«.BUFF>,«,WCNT>, ,*0#2l, 

.ENDM 

.macro  • Bern 

...CM3  ,4, 

.ENOM 
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, MAC*0  •  SfcTTOP  .ADO 

,IIF  NS  < . *DO> ,  MOV  ,ADO,X0 

EMT  aQ354 

,EnOm 

.mACKO  .SFPA  , AR£A , .ADD 
,  ,  . CM 1  <.AHEA»,24. 

...CM2  <.A0u»,2.,X 

.ENOM 


, MACHO  .SPPuN  .AREA, .CHAN, .CODE, .BUFF, .WCNT, .BLK, ,CRTN 
,,,CM1  <. AREA*, 26. ,«. CHAN* 

...CM2  «.BUK>,2. 

...CM2  * .BUFF*, 4 . 

,,,CM2  <.WCnT>,6» 

.IF  NB  .CODE 

MQVd  #a0377,8. (0) 

MO V  3  .CODE, 9.(0) 

,ENDC 

.IF  B  ,CHTN 

CcR  10.(0) 


.IPF 

MOV  .CRTN,  10,(0) 

,  ENDC 

6MT  A0375 

,ENOM 


.MACHO  .SHEsET 
.ENOM 


EMT  a0392 


.MACHO  ,3pnd 
...CM3  ,1 
.ENOM 

.macho  .synch  .area 

,  I  IF  NS  «,  AREA*,  MQV  .AHEA.X4 

MOV  t«A094,X5 

JSR  5,,#A0324(3.) 

.ENOM  , 


.MACHO  .tloch 
,  ,  .CM3  , 7 , 
.ENOM 


.MACHO  .THPStT  .AREA, .ADD 
...CM!  < • AREA* , 3 . 

...CM2  «.A0o>,2.,X 

.ENOM 


.macho  .TTInH 

,  ENOM 

.MACRO  .TTYIN  .CHAR 

.IIP  NB  «,CHAR», 
.ENOM 


tMT 


EMT 

DCS 

M0V8 


AQ340 


AQ340 

.•2 

X0, .CHAR 


D-8 


AQ341 


System  Macro  File 


MACHO 


.ttuutr 


.enom 


EMT 


.MACHO  .TTYOOT  .CHAR 
,  I  IF  NB  < , CH AR* ,  M0V9 

EMT 

»CS 

.ENOM 

.MACRO  .THAU  .AREA, ,TIm& 

...CHI  «. AREA*, 20. 

« « • CM2  w»TlMfe*,2.,X 

.ENOM 


• CHAH , X0 
AQ341 
.•2 


.MACHO  .unlock 

.ENOM 

.macro  .wait  .Chan 

.IF  NOF  . . . V2 

.iff 

...CM3  < . CHAN> ,  fc? 

.  ENOC 
.ENOM 

.macho  .write  .area, ,cman, .buff, ,wcnt,.blk 

.IF  NDF  ,,,v2 


EMT  aQ34? 


EMT  aq<240*,CHAN* 


» I IF  NB  «.#CNT», 

MOV 

.WCNT , %0 

MOV 

#1 , ■ (6. ) 

MOV 

,BUFF,-C6.) 

MOV 

.CHAN, -(6.) 

EMT 

AQ42204, AREA# 

.iff 

...CM4  «. AREA*, <.CMAN»,«. BUFF*, 

<. WCNT*, c.BLK#, #1,9. 

.ENOC 

.ENOM 

.MACHO  .WRIT#  .AREA, 

.CHAN, .BUFF 

, .WCNT , ,bLK 

.IF  NOF  ,,,V2 

,IIF  NB  # . WCN T» , 

MOV 

.WCNT,X0 

CLR 

•(6.) 

MOV 

.BUFF, .(6.) 

MOV 

.CHAN, •(6.) 

EMT 

aO<220*. AREA* 

.iff 


, ,.CM4  <, AREA*, «,CHAN»,*,BUFF»,<,RCnT>,<,BLK*, #0,9. 

.ENOC 

.ENOM 


.MACHO  .WRlTC  .AREA, .CHAN, .BUFF,, 
.IF  NOF  ...V2 
.  I IF  NB  <.C*TN>, 


N, .BUFF 

,  .WCNT, .CHTN, . 

MOV 

.CRTN,X0 

MOV 

.WCNT, .(6.) 

MOV 

.BUFF, .(8.) 

MOV 

.CHAN, .(6.) 

EmT 

aQ<220+, AREA* 

.iff 

...CM4  <,AREA»,<,CMAN>,4,8UFF»,<.#CnT>,«.BLK>,<.CRTN*,9. 
.ENOC 
.ENOM 
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APPENDIX  E 


PROGRAMMED  REQUEST  SUMMARY 


E.l  PARAMETERS 

The  following  parameters  are  used  as  arguments  in  various  calls.  (Any 
parameters  used  which  are  not  mentioned  here  are  particular  to  a 
request  and  the  appropriate  section  in  Chapter  9  should  be  consulted.) 

Parameter  Description 

.addr  an  address,  the  meaning  of  which  depends  on 

the  request  being  used 


.area 

.blk 

.buff 

.chan 

.crtn 

.count 

.dblk 

.num 

•went 


a  pointer  to  the  EMT  argument  list 

a  block  number  specifying  the  relative  block 
in  a  file  where  an  I/O  operation  is  to  begin 

a  buffer  address  specifying  a  memory  location 
into  which  or  from  which  an  I/O  transfer  is 
to  be  performed 

a  channel  number  in  the  range  0-377  (octal) 

the  entry  point  of  a  completion  routine 

file  number  for  magtape/cassette  operations 

the  address  of  a  four-word  RAD50  descriptor 
of  the  file  to  be  opened 

a  number,  the  value  of  which  depends  on  the 
request 

a  word  count  specifying  the  number  of  words 
to  be  transferred  to  or  from  the  buffer 
during  an  I/O  operation 


E.2  REQUEST  SUMMARY 

Refer  to  Appendix  D  (SYSMAC.SML)  to  see  how  each  macro  call  is 
expanded  in  assembly  language  code. 
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APPENDIX  F 

BASIC/RT-11  LANGUAGE  SUMMARY 


BASIC/RT-11  is  a  single-user  conversational  BASIC  for  use  under  the 
RT-11  system.  While  the  BASIC  language  is  one  of  the  simplest 
computer  languages  to  learn,  it  contains  advanced  techniques  which  the 
experienced  programmer  can  use  to  perform  more  intricate  manipulations 
or  to  express  a  problem  more  efficiently. 

BASIC/RT-11  interfaces  with  the  RT-11  monitor  to  provide  powerful 
sequential  and  random-access  file  capabilities  and  allows  the  user  to 
save  and  retrieve  programs  from  peripheral  devices.  BASIC/RT-11  has 
provision  for  alphanumeric  character  string  I/O  and  string  variables 
(12K  or  larger  systems)  and  allows  user-defined  functions  and  assembly 
language  subroutine  calls  from  user  BASIC  programs. 

For  details  on  using  the  BASIC  language,  and  for  instructions  on 
running  BASIC/RT-11,  refer  to  the  BASIC/RT-11  LANGUAGE  REFERENCE 
MANUAL  ( DEC- 11-LBACA-A-D) .  A  summary  of  the  BASIC/RT-11  commands  and 
error  messages  is  included  here  for  quick  reference. 


F.l  BASIC/RT-11  STATEMENTS 

The  following  summary  of  BASIC  statements  defines  the  general  format 
for  the  statement  and  gives  a  brief  explanation  of  its  use. 


CALL  "function  name"  [ (argument  list) ] 

Used  to  call  assembly  language  user 
functions  from  a  BASIC  program. 


CHAIN "file  descriptor"[LINE  number] 

Terminates  execution  of  user  program , 
loads  and  executes  the  specified  program 
starting  at  the  line  number,  if 
included. 


Closes  the  logical  file  specified.  If 
no  file  is  specified,  closes  all  files 
which  are  open. 


DATA  data  list 


Used  in  conjunction  with  READ  to  input 
data  into  an  executing  program. 
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DEF  FNletter  (argument) =expression 

Defines  a  user  function  to  be  used  in 
the  program  (letter  is  any  alphabetic 
letter) . 

DIM  variable(n),  variable (n,m) ,variable$ (n) ,variable$ (n,m) 

Reserves  space  for  lists  and  tables 
according  to  subscripts  specified  after 
variable  name. 


END 


Placed  at  the  physical  end  of  the 
program  to  terminate  program  execution. 


FOR  variable  =  expressionl  TO  expression2  STEP  expressions 

Sets  up  a  loop  to  be  executed  the 
specified  number  of  times. 


GOSUB  line  number 


GO  TO  line  number 


Used  to  transfer  control  to  a  specified 
line  of  a  subroutine. 

Used  to  unconditionally  transfer  control 
to  other  than  the  next  sequential  line 
in  the  program. 


IF  expression  rel.op.  expression! THEN  l  line  number 

1G0  TO] 


IF  END  #nfTHEN  \  line  number 


V 


GO  TO 


■)“ 


INPUT  list 

INPUT  #expression:  list 
[LET]  variable=expression 
[LET]  VFn(i)=expression 
NEXT  variable 


Used  to  conditionally  transfer  control 
to  the  specified  line  of  the  program. 


Used  to  test  for  end  file  on  sequential 
input  file  #n. 

Used  to  input  data  from  the  terminal 
keyboard  or  papertape  reader. 

Inputs  from  a  sequential  file  or 
particular  device. 

Used  to  assign  a  value  to  the  specified 
variable. 


Used  to  set  the  value 
memory  file  element. 


of  a  virtual 


ile  £ 


OPEN  file  FOR 


f INPUT 
1  OUTPUT 


.}] 


t 


OPEN  file  I  FOR  f  INPUT  ^1 

]  output/ 


Placed  at  the  end  of  a  FOR  loop  to 
return  control  to  the  FOR  statement. 

[(b)]  AS  FILE  #n  [DOUBLE  BUF] 

Opens  a  sequential  file  for  input  or 
output  as  specified.  File  may  be  of  the 
form  ”dev:filnam,extM  or  a  scalar  string 
variable.  The  number  of  blocks  may  be 
specified  by  b. 

[(b)]  AS  FILE  VFnx  (dimension) =string  length 

Opens  a  virtual  memory  file  for  input  or 
output.  x  represents  the  type  of  files 
floating  point  (blank) ,  integer  (%) ,  or 
character  strings  ($).  File  may  be  of 
the  form  Mdev:fil.extM  or  a  scalar 
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OVERLAY  "file  descriptor" 

PRINT  list 

PRINT  "text" 


string  variable.  The  number  of  blocks 
may  be  specified  by  b. 

Used  to  overlay  or  merge  the  program 
currently  in  memory  with  a  specified 
file,  and  continue  execution. 

Used  to  output  data  to  the  terminal. 
The  list  can  contain  expressions  or  text 
strings. 

Used  to  print  a  message  or  a  string  of 
characters . 


PRINT  #expression:  expression  list 

Outputs  to  a  particular  output  device, 
as  specified  in  an  OPEN  statement. 

PRINT  TAB(x) ;  Used  to  space  to  the  specified  column. 

RANDOMIZE  Causes  the  random  number  generator  to 

calculate  different  random  numbers  every 
time  the  program  is  run. 

READ  variable  list  Used  to  assign  the  values  listed  in  a 

DATA  statement  to  the  specified 
variables. 


REM  comment 

RESTORE 

RESTORE  #n 

RETURN 

STOP 


Used  to  insert  explanatory  comments  into 
a  BASIC  program. 

Used  to  reset  data  block  pointer  so  the 
same  data  can  be  used  again. 

Rewinds  the  input  sequential  file  #n  to 
the  beginning. 

Used  to  return  program  control  to  the 
statement  following  the  last  GOSUB 
statement. 

Used  at  the  logical  end  of  the  program 
to  terminate  execution. 


F.2  BASIC/RT-11  COMMANDS 

The  following  key  commands  halt  program  execution,  erase  characters  or 
delete  lines. 

Key  Explanation 

ALTMODE  Deletes  the  entire  current  line.  Echoes  DELETED 

message  (same  as  CTRL  U) .  On  some  terminals  the 
ESC  key  must  be  used. 

CTRL  C  Interrupts  execution  of  a  command  or  program  and 

returns  control  to  the  RT-11  monitor.  BASIC  may 
be  restarted  without  loss  of  the  current  program 
by  using  the  monitor  REENTER  command. 
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CTRL  O  Stops  output  to  the  terminal  and  returns  BASIC  to 

the  READY  message  when  program  or  command 
execution  is  completed. 

CTRL  U  Deletes  the  entire  current  line.  Echoes  DELETED 

message  (same  as  ALTMODE) . 

*-  (SHIFT  0)  Deletes  the  last  character  typed  and 

echoes  a  backarrow  (same  as  RUBOUT) .  On  VT05  or 
LA30  use  the  underscore  (_)  key. 

RUBOUT  Deletes  the  last  character  typed  and  echoes  a 

backarrow  (same  as  +-) . 

The  following  commands  list,  punch,  erase,  execute  and  save  the 
program  currently  in  memory. 


Command 

Explanation 

CLEAR 

Sets  the  array  and  string  buffers 
and  zeroes. 

to 

nulls 

LIST 

Prints  the  user  program  currently 
on  the  terminal. 

in 

memory 

LIST  line  number 

LIST  -line  number 

LIST  line  number- [END] 

LIST  line  number-line  number 

Types  out  the  specified  program  line(s)  on 
the  terminal. 


LISTNH  line  number 
LISTNH  -line  number 
LISTNH  line  number- [END] 

LISTNH  line  number-line  number 


Lists  the  lines  associated  with  the  specified 
numbers  but  does  not  print  a  header  line. 

NEW  "filnam" 

Does  a  SCRatch  and  sets  the  current  program 
name  to  the  one  specified. 

OLD  "file" 

Does  a  SCRatch  and  inputs  the  program  from 
the  specified  file. 

RENAME  "filnam" 

Changes  the  current  program  name  to  the  one 
specified. 

REPLACE  "dev s filnam 

.ext” 

Replaces  the  specified  file  with  the  current 
program. 

RUN 

Executes  the  program  in  memory. 

RUNNH 

Executes  the  program  in  memory  but  does  not 
print  a  header  line. 

SAVE  "dev: filnam. ext" 

Outputs  the  program  in  memory  as  the 
specified  file. 
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SCRatch  Erases  the  entire  storage  area. 

F. 3  BASIC/RT-11  FUNCTIONS 


The  following 
BASIC. 

functions  perform  standard  mathematical  operations  in 

Name 

Explanation 

ABS(x) 

Returns  the  absolute  value  of  x. 

ATN(x) 

Returns  the  arctangent  of  x  as  an  angle  in  radians 
in  the  range  +  or  -  pi/2. 

BIN (x$) 

Computes  the  integer  value  of  a  string  of  blanks 
(ignored),  l's  and  0's. 

COS  (x) 

Returns  the  cosine  of  x  radians. 

EXP (x) 

Returns  the  value  of  etx  where  e=2. 71828. 

INT  (x) 

Returns  the  greatest  integer  less  than  or  equal  to 

X. 

LOG (x) 

Returns  the  natural  logarithm  of  x. 

OCT (x$) 

Computes  an  integer  value  from  a  string  of  blanks 
(ignored)  and  digits  from  0  to  7. 

RND(x) 

Returns  a  random  number  between  0  and  1. 

SGN(x) 

Returns  a  value  indicating  the  sign  of  x. 

SIN (x) 

Returns  the  sine  of  x  radians. 

SQR(x) 

Returns  the  square  root  of  x. 

TAB  (x) 

Causes  the  terminal  type  head  to  tab  to  column 
number  x. 

The  string  functions  are: 


ASC (x$) 

Returns  as  a  decimal  number  the  seven-bit  internal 
code  for  the  one-character  string  (x$) . 

CHR$ (x) 

Generates  a  one-character  string  having  the  ASCII 
value  of  x. 

DAT$ 

Returns  the  current  date  in  the  format  07-MAY-73. 

LEN (x$) 

Returns  the  number  of  characters  in  the  strinq 
(x$). 

POS(x$,y$,z)  Searches  for  and  returns  the  position  of  the  first 
occurrence  of  y$  in  x$  starting  with  the  zth 
position. 
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SEG$(x$,y,z) 

STR$ (x) 

TRM$(X$) 

VAL (x$) 


Returns  the  string  of  characters  in  positions  y 
through  z  in  x$. 

Returns  the  string  which  represents  the  numeric 
value  of  x. 

Returns  x$  without  trailing  blanks. 

Returns  the  number  represented  by  the  string  (x$) . 


F.4  BASIC/RT-11  ERROR  MESSAGES 


Abbrevia¬ 
tion _  Message  Explanation 

?ARG  ARGUMENT  ERROR  AT  LINE  xxxxx 

Arguments  in  a  function  call  do  not 
match  (in  number  or  in  type)  the 
arguments  defined  for  the  function. 

?ATL  ARRAYS  TOO  LARGE  AT  LINE  xxxxx 

There  is  not  enough  room  in  the  memory 
available  for  the  arrays  specified  in 
the  DIM  statements. 

?BDR  BAD  DATA  READ  AT  LINE  XXXXX 

Item  input  from  DATA  statement  list  by 
READ  statement  is  bad. 

?BRT  BAD  DATA- RETYPE  FROM  ERROR 

Item  entered  to  input  statement  is  bad. 

?BSO  BUFFER  STORAGE  OVERFLOW  at  line  xxxxx 

Not  enough  room  available  in  file 
buffers. 

?DCE  DEVICE  CHANNEL  ERROR  AT  LINE  XXXXX 

The  device  channel  number  specified  for 
a  sequential  or  virtual  memory  file  is 
out  of  range  (1-7) ,  or  an  attempt  was 
made  to  open  a  virtual  memory  file  on  a 
non-file  structured  device. 

?DNR  DEVICE  NOT  READY  An  OLD  command  read  a  file  which  did  not 

have  any  BASIC  statements. 

?DV0  DIVISION  BY  0  AT  LINE  xxxxx 

Program  attempted  to  divide  some 
quantity  by  0. 
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?ETC  EXPRESSION  TOO  COMPLEX  AT  LINE  xxxxx 

The  expression  being  evaluated  caused 
the  stack  to  overflow  (usually  because 
the  parentheses  are  nested  too  deeply) . 
The  degree  of  complexity  that  produces 
this  error  varies  according  to  the 
amount  of  space  available  in  the  stack 
at  the  time.  Breaking  the  statement 
into  several  simpler  ones  eliminates  the 
error. 

?FDE  FILE  DATA  ERROR  AT  LINE  xxxxx 

Tried  to  write  an  element  on  an  integer 
virtual  memory  file  outside  the  range 
(x) <32,768. 

?FIO  FILE  I/O  ERROR  AT  LINE  xxxxx 

An  I/O  error  occurred.  All  files  are 
automatically  closed. 

?FNF  FILE  NOT  FOUND  AT  LINE  xxxxx 

The  file  requested  was  not  found  on  the 
specified  device. 

?FNO  FILE  NOT  OPEN  AT  LINE  xxxxx 

The  sequential  or  virtual  memory  file 
referenced  is  not  open. 

?FTS  FILE  TOO  SHORT  AT  LINE  xxxxx 

The  sequential  file  space  allocated  to 
an  output  file  is  inadequate. 

?FWN  FOR  WITHOUT  NEXT  AT  LINE  xxxxx 

The  program  contains  a  FOR  statement 
without  a  corresponding  NEXT  statement 
to  terminate  the  loop. 

?GND  GOSUBS  NESTED  TOO  DEEPLY  AT  LINE  xxxxx 

Program  GOSUBS  nested  to  more  than  20 
levels. 

?IDF  ILLEGAL  DEF  AT  LINE  xxxxx 

The  DEF  statement  contains  an  error. 

?IDM  ILLEGAL  DIM  AT  LINE  xxxxx 

Syntax  error  in  a  dimension  statement. 

?ILN  ILLEGAL  NOW  An  attempt  was  made  to  execute  an  INPUT 

statement  in  immediate  mode. 

?ILR  ILLEGAL  READ  AT  LINE  xxxxx 

Tried  to  open  a  write-only  device  for 
input  or  tried  to  read  on  a  sequential 
file  open  for  output. 

?LTL  LINE  TOO  LONG  The  line  being  typed  is  longer  than  120 

characters;  the  line  buffer  overflows. 
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?NBF 

NEXT  BEFORE  FOR  AT  LINE  XXXXX 

The  NEXT  statement  corresponding  to  a 
FOR  statement  precedes  the  FOR 
statement. 

?NER 

NOT  ENOUGH  ROOM  AT  LINE  xxxxx 

There  is  not  enough  room  on  the  selected 
device  for  the  specified  number  of 
output  blocks. 

?NPR 

NO  PROGRAM  The  RUN  command  has  been  specified,  but 

no  program  has  been  typed  in. 

?NSM 

NUMBERS  AND  STRINGS  MIXED  AT  LINE  xxxxx 

String  and  numeric  variables  may  not 
appear  in  the  same  expression,  nor  may 
they  be  set  equal  to  each  other  (as  in 
A$=2) . 

?00D 

OUT  OF  DATA  AT  LINE  xxxxx 

The  data  list  was  exhausted  and  a  READ 
requested  additional  data. 

?OVF 

OVERFLOW  AT  LINE  xxxxx 

The  result  of  a  computation  is  too  large 
for  the  computer  to  handle. 

?PTB 

PROGRAM  TOO  BIG  The  line  just  entered  caused  the  program 

to  exceed  the  user  code  area. 

?PWF 

POWER  FAIL  AT  LINE  xxxxx 

A  power  fail  occurred  while  the 

specified  line  was  being  executed. 

?RBG 

RETURN  BEFORE  GOSUB  AT  LINE  xxxxx 

A  RETURN  was  encountered  before 

execution  of  a  GOSUB  statement. 

?SOB 

SUBSCRIPT  OUT  OF  BOUNDS  AT  LINE  xxxxx 

The  subscript  computed  is  greater  than 
32,767  or  is  outside  the  bounds  defined 
in  the  DIM  statement. 

?SSO 

STRING  STORAGE  OVERFLOW  AT  LINE  xxxxx 

There  is  not  enough  memory  available  to 
store  all  the  strings  used  in  the 
program. 

?STL 

STRING  TOO  LONG  AT  LINE  xxxxx 

The  maximum  length  of  a  string  in  a 
BASIC  statement  is  255  characters. 

?SYN 

SYNTAX  ERROR  AT  LINE  xxxxx 

The  program  has  encountered  an 
unrecognizable  statement.  Common 
examples  of  syntax  errors  are  misspelled 
commands  and  unmatched  parentheses,  and 
other  typographical  errors. 

?TLT 

LINE  TOO  LONG  TO  TRANSLATE 

Lines  are  translated  as  entered,  and  the 
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line  just  entered  exceeds  the  area 
available  for  translation. 

?UFN  UNDEFINED  FUNCTION  AT  LINE  xxxxx 

The  function  called  was  not  defined  by 
the  program  or  was  not  loaded  with 
BASIC. 

?ULN  UNDEFINED  LINE  NUMBER  AT  LINE  xxxxx 

The  line  number  specified  in  an  IF,  GO 
TO  or  GOSUB  statement  does  not  exist 
anywhere  in  the  program. 

?WLO  WRITE  LOCKOUT  AT  LINE  xxxx 

Tried  to  open  a  read-only  device  for 
output,  or  tried  to  write  on  a 
sequential  or  virtual  file  opened  for 
input  only. 

?tER  t  ERROR  AT  LINE  xxxxx 

The  program  tried  to  compute  the  value 
AtB,  where  A  is  less  than  0  and  B  is  not 
an  integer.  This  produces  a  complex 
number  which  is  not  represented  in 
BASIC.  . 


Function  Errors 

The  following  errors  can  occur  when  a  function  is  called  improperly. 

?ARG  The  argument  used  is  the  wrong  type  (for 

example,  the  argument  was  numeric  and  the 
function  expected  a  string  expression) . 

?SYN  The  wrong  number  of  arguments  was  used  in  a 

function,  or  the  wrong  character  was  used  to 
separate  them  (for  example,  PRINT  SIN(X,Y) 
produces  a  syntax  error) . 


In  addition. 

the  functions  give  the  errors  listed  below. 

FNa (...) 

?UFN 

The  function  a  has  not  been  defined  (function 
cannot  be  defined  by  an  immediate  mode 
statement) . 

RND  or  RND(x) 

No  errors. 

SIN (x) 

No  errors. 

COS (x) 

No  errors. 

SQR(x) 

?ARG 

x  is  negative. 

ATN(x) 

No  errors. 

EXP (x) 

?tER 

x  is  greater  than  87. 

LOG (x) 

?ARG 

x  is  negative  or  0. 
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ABS(x) 

No  errors. 

INT(x) 

No  errors. 

SGN(x) 

No  errors. 

TAB  (x) 

?ARG 

x  is  not  in  the  range  0<=x<256. 

LEN (a$) 

No  errors. 

ASC (A$) 

?ARG 

A$  is  not  a  string  of  length  1. 

CHR$ (x) 

?ARG 

x  is  not  in  the  range  0<=x<256. 

DAT$ 

No  errors. 

POS(a$,b$,n) 

No  errors. 

SEG$ (a$ ,nl ,n2) 

No  errors. 

TRM$(a$) 

No  errors. 

VAL(a$) 

?ARG 

A$  is  not  a  valid  numeric  expression. 

STR$ (x) 

No  errors. 

BIN (x$) 

?ARG 

Character  other  than  blank,  0  or  1  in  string. 

OCT (x$) 

?ARG 

Character  other  than  blank  or  0  through  7  in 
string. 
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FORTRAN  LANGUAGE  SUMMARY 


FORTRAN  IV  is  a  problem-solving  language  designed  to  allow  scientists 
and  engineers  to  express  mathematical  operations  in  a  familiar  format. 

A  FORTRAN  source  program  is  composed  of  a  series  of  statements. 
Statements  are  usually  made  up  of  one-  or  two-word  commands,  which, 
when  used  in  conjunction  with  data  variables  and  constants,  can  be 
used  to  control  program  execution,  assign  values  to  variables  and  read 
and  write  data.  The  FORTRAN  library  contains  routines  to  simplify 
mathematical  functions  such  as  computing  sines,  cosines,  square  roots, 
etc.  The  source  program  is  translated  by  the  FORTRAN  compiler  into  a 
machine  language  program  which,  when  linked  with  the  FORTRAN  object 
time  routines ,  can  be  executed  by  the  computer. 

This  appendix  describes  first  how  to  run  a  FORTRAN  program  as  a 
foreground  job,  and  then  summarizes  briefly  the  RT-11  FORTRAN  IV 
language,  statements,  and  error  messages.  For  details,  refer  to  the 
PDP-11  FORTRAN  LANGUAGE  REFERENCE  MANUAL  (DEC-ll-LFLRA-A-D)  and  THE 
RT-11  FORTRAN  COMPILER  AND  OBJECT  TIME  SYSTEM  USER'S  MANUAL 
(DEC-ll-LRFPA— A-D) . 


G.l  RUNNING  A  FORTRAN  PROGRAM  IN  THE  FOREGROUND 

Since  the  FORTRAN  Object  Time  System  needs  work  areas  to  perform  some 
of  its  functions,  the  FRUN/Nsx  monitor  command  must  be  used  to 
allocate  the  needed  space  when  running  a  FORTRAN  program  as  a 
foreground  job.  The  following  formula  cam  be  used  to  calculate  the 
number  (x)  which  must  be  designated  to  the  /N  option: 

x  =  y  +  21  octal (N)  +  (R-210  octal)  +  A*400  octal 

where : 

Y  *  264  octal. 

N  =  the  value  of  the  /N  FORTRAN  compiler  switch  option  (the 

compiler  defaults  this  to  6  octal) . 

R  **  the  value  of  the  /R  FORTRAN  compiler  switch  option  (the 

compiler  defaults  this  to  210  octal,  136  decimal). 
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A  =  the  number  of  I/O  buffers  in  simultaneous  use  during 
execution.  (Console  terminal  I/O  does  not  require  any 
buffers.  Each  open  logical  unit  typically  requires  one 
buffer. ) 

For  example,  to  calculate  x  for  a  program  (FILENA.REL)  which  uses  only 
terminal  I/O  and  allows  the  compiler  to  assign  the  standard  defaults, 
set  the  formula  as  follows  (all  values  are  octal) : 


x  =  264  +  21(6)  +  (210-210)  +  0*400 


432  octal  words  are  required.  The  FORTRAN  program  is  executed  using 
the  FRUN  command  as  shown: 


.FRUN  FILENA.REL/N:432  <CR> 


NOTE 


An  exception  can  occur  if  the  size  of 
the  linked  FORTRAN  program  is  less  than 
the  size  of  the  USR  (2K)  and  the  USR  is 
to  be  swapped.  In  this  case,  additional 
space  must  be  allocated  to  allow  the  USR 
to  successfully  swap  over  the  linked 
FORTRAN  program.  The  additional  space 
needed  may  be  calculated  by  subtracting 
the  size  of  the  linked  FORTRAN  program 
from  10000  octal  bytes  (the  size  of  the 
USR)  and  adding  this  result  to  the  value 
of  x  previously  calculated. 


G.2  FORTRAN  CHARACTER  SET 

The  characters  that  may  appear  in  a  FORTRAN  statement  are  restricted 
to  those  listed  below. 

1.  The  letters  A  through  Z 

2.  The  numerals  0  through  9 

3.  The  following  "special"  characters: 


Character 


Name 


Space  or  Blank 
Equals 


+ 


Plus 


Minus 


* 


Asterisk 


/ 


Slash 


Left  Parenthesis 
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)  Right  Parenthesis 

t  Comma 

•  Decimal  Point 


,  Apostrophe 

"  Double  Quote 

$  Dollar  Sign 


Other  printable  characters  may  appear  in  a  FORTRAN  statement  only  as 
part  of  a  Hollerith  constant  or  alphanumeric  literal.  Any  printable 
character  may  appear  in  a  comment. 


G. 3  EXPRESSION  OPERATORS 


Each  group  of  operators  is  shown  in  order  of  descending  precedence 
during  execution. 


Type  Operator 


Arithmetic 

**  exponentiation 

*»/  multiplication, 

division, 

+,-  addition, subtraction 

-  unary  minus 

Relational 


Operates  Upon 


numeric  constants, 
variables  and 
expressions 


.GT. 

.GE. 

.LT. 

.LE. 

.EQ. 

.NE. 

Logical 

.NOT. 


.AND. 


.OR. 


greater  than 
greater  than  or 
equal  to 
less  them 
less  than  or 
equal  to 
equal  to 
not  equal  to 


.NOT. A  is  true  if  and 
only  if  A  is  false, 
and  is  false  if  A  is 
true. 


A.AND.B  is  true  if 
and  only  if  A  and  B 
are  both  true  and  is 
false  if  either  A  or 
B  is  false. 

A.OR.B  is  true  if  and 
only  if  either  A  or 


variables , 
constants, 
and  arithmetic 
expressions  (all 
relational  operators 
have  equal  priority) 


logical  variables, 
logical  constants, 
integer  variables 
and  constants,  logical 
integers  and  expressions. 
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B  or  both  A  and  B 
are  true,  and  false 
if  both  A  and  B 
are  false. 

.EQV.  A.EQV.B  is  true  if  and 

only  if  A  and  B 
are  both  true  or  if  A 
and  B  are  both  false. 

.XOR.  A.XOR.B  is  true  if  and  only 

if  A  is  true  and  B  is 
false  or  if  B  is  true 
and  A  is  false. 


G.4  SUMMARY  OF  FORTRAN  STATEMENTS 

The  following  is  a  summary  of  statements  available  in  the  PDP-11 
FORTRAN  IV  language,  including  the  general  format  for  the  statement 
and  its  effect. 


Statement  Formats 


Effect 


Arithmetic/Logical  Assignment 


variable=expression 


The  value  of  the  arithmetic  or 
logical  expression  is  assigned 
to  the  variable. 


( 

Arithmetic  Statement  Functions 


name (varl,var2 , . . . ) =expression 


ACCEPT 

ACCEPT  f,list 


ASSIGN 

ASSIGN  n  TO  ivar 


Creates  a  user-defined 
function  having  the  variables 
(var)  as  dummy  arguments. 
When  referenced,  the 
expression  is  evaluated  using 
the  actual  arguments  in  the 
function  call. 


Reads  input  from  logical  unit 
5  (TTs  is  default);  f  is  the 
format  statement  label  and 
list  is  an  optional  data  list. 


Assigns  the  statement  number  n 
to  the  integer  variable  ivar. 
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BACKSPACE 

BACKSPACE  u 

BLOCK  DATA 

BLOCK  DATA 

CALL 

CALL  name 

CALL  name  ( argl ,  arg2 , . . ♦ ) 


The  currently  open  file  on 
logical  unit  number  u  is 
backspaced  one  record. 


Specifies  the  subprogram  which 
follows  as  a  BLOCK  DATA 
subprogram. 


Calls  the  SUBROUTINE 
subprogram  with  the  name 
specified ,  passing  the  actual 
arguments  (arg)  to  replace  the 
dummy  arguments  in  the 
SUBROUTINE  definition. 


COMMON 

COMMON/namel/varl ,  var2 , . . ./namel/var ( j ) ,var (k) 

Reserves  one  or  more  blocks  of 
storage  space  under  the  name 
specified  to  contain  the 
variables  (var)  associated 
with  that  block  name. 

CONTINUE 

CONTINUE  Causes  no  processing. 

DATA 

DATA  varl,  var 2 , . . ./vail,  val2,.../ 

Causes  elements  in  the  list  of 
values  (val)  to  be  initially 
stored  in  the  corresponding 
elements  of  the  list  of 
variable  names  (var) . 

DECODE 

DECODE  (c,f,v)list  Changes  the  elements  in  the 

list  of  variables  from  ASCII 
into  the  desired  internal 
format;  c  is  the  number  of 
characters ,  f  is  the  format , 
and  v  is  the  name  of  an  array. 
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DEFINE  FILE 

DEFINE  FILE  u (m,n,U, lvar) , . . • 


DIMENSION 

DIMENSION  sl,s2,...,sk 


DO 

DO  n  lvar  =  el,e2,e3 


END 

END 

ENCODE 

ENCODE  (c, f ,v) list 


END  FILE 

END  FILE  u 


Defines  the  record  structure 
of  a  disk  or  DECtape  direct 
access  file  where  u  is  the 
logical  unit  number ,  m  is  the 
number  of  fixed  length  records 
in  the  file,  n  is  the  length 
in  words  of  a  single  record ,  U 
is  a  fixed  argument ,  and  lvar 
is  the  associated  variable 
pointing  to  the  next  record. 


Reserves  storage  space  for  the 
specified  array (s).  Each  s 
consists  of  an  array  variable 
name  followed  by  up  to  seven 
integer  constants ,  separated 
by  commas  and  enclosed  in 
parentheses • 


1.  Sets  integer  variable  ivar 
=  to  expression  (el,  e2, 
e3  must  result  in  an 
integer  quantity) 

2.  Executes  statements 
through  statement  number  n 

3.  Increments  lvar  =  lvar+e3 

4.  If  e3>0  and  ivar  <=e2,  or 
e3<0  and  ivar  >=e2,  goes 
back  to  2  above 


Delimits  a  program  unit. 


Changes  the  elements  in  the 
list  of  variables  into  ASCII 
format;  c  is  the  number  of 
characters  in  the  buffer,  f  is 
the  format  statement  number, 
and  v  is  the  name  of  the  array 
to  be  used  as  the  resulting 
buffer. 


The  file  currently  open  on 
logical  unit  number  u  is 
closed. 
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EQUIVALENCE 

EQUIVALENCE  (varl,var2, . . .) , (var j ,vark, . . . ) 


Each  of  the  variables  within  a 
set  of  parentheses  is  assigned 
the  same  storage  location. 


EXTERNAL 

EXTERNAL  namel , name 2 , . . . 


FIND 

FIND(u'r) 


FORMAT 

n  FORMAT (field  specification,...) 


FUNCTION 

FUNCTION  name 

FUNCTION  name  ( varl , var2 , . .  . ) 
type  FUNCTION  name  (varl,var2, . . . ) 


GOTO 

Unconditional 
GOTO  n 


Informs  the  system  that  the 
names  specified  are  those  of 
FUNCTION  or  SUBROUTINE 
subprograms. 


Positions  the  direct  access 
file  on  logical  unit  number  u 
to  record  r  and  sets  the 
associated  variable  to  record 
number  r. 


Describes  the  format  in  which 
one  or  more  records  are  to  be 
transmitted;  the  statement 
number  n  must  be  specified 
(the  field  specifications  may 
include  the  field  descriptors, 
I,  0,  F,  E,  D,  G,  L,  A,  H,  X, 
T,  Q,  and  $,  delimited  by 
field  separators  ,  and  /) . 


Begins  a  FUNCTION  subprogram, 
indicating  the  program  name 
and  any  dummy  variable  names 
(var) .  An  optional  type 
specification  can  be  included. 


Transfers  control  to  statement 
number  n. 


G-7 


FORTRAN  Language  Summary 


Computed 

GOTO  (kl,k2,...,kn) ,e 

Assigned 

GOTO  ivar 

GOTO  ivar, (kl,k2, . . . ,kn) 


Transfers  control  to  the 
statement  number  ki  where  i  = 
value  of  expression  e.  If  e<l 
or  e>n  no  transfer  takes 
place. 


Transfers  control  to  the 
statement  most  recently 
associated  with  ivar  by  an 
ASSIGN  statement. 


IF 

Arithmetic 

IF  (expression)  nl,n2,n3 


Logical 

IF  (expression)  statement 
IMPLICIT 

IMPLICIT  type  (al,bl-b2 ,...),.. . 


PAUSE 

PAUSE 

PAUSE  display 


Transfers  control  to  statement 
number  n  depending  upon  the 
value  of  the  expression.  If 
the  value  of  the  expression  is 
less  than  zero,  transfers  to 
nl;  if  the  value  of  the 
expression  is  equal  to  zero, 
transfers  to  n2,  if  the  value 
of  the  expression  is  greater 
them  zero,  transfers  to  n3. 


Executes  the  statement  if  the 
logical  expression  tests  true. 


The  elements  a  and  b  represent 
single  (or  a  range  of) 
letter (s)  whose  presence  as 
the  initial  letter  of  a 
variable  specifies  the 
variable  to  be  of  that  type, 
if  that  variable  is  not 
explicitly  given  a  type. 


Suspends  program  execution  and 
prints  the  octal  constant, 
Hollerith  constant,  or 
alphanumeric  literal  display, 
if  one  is  specified.  Program 
execution  is  resumed  by  typing 
a  carriage  return. 
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PRINT 


PRINT  f , list  Writes  output  on  logical  unit 

6  (LPs  is  default);  f  is  the 
format  statement  label  and 
list  is  an  optional  data  list. 


READ 

Formatted 


Reads  at  least  one  logical 
record  from  device  u  according 
to  format  specification  f  and 
assigns  values  to  the 
variables  in  the  list. 
Logical  unit  number  1  is  used 
as  default  in  the  third  form 
above. 

Unformatted 
READ  (u) 

READ(u)  list  Reads  one  logical  record  from 

device  u,  assigning  values  to 
the  variables  in  the  list. 


Direct  Access 

READ (u'r) list  Reads  from  logical  unit  number 

u,  record  number  r,  and 
assigns  values  to  the 
variables  in  the  list. 


READ (u,f ) 

READ (u,f) list 
READ  f  ,  list 


Transfer  of  Control  on  Error 


END=n 

ERR=m 

END=n,ERR=m  Optional  elements  in  the  READ 

statement  list  (e.g., 

READ (u,f  ,  END=n ,  ERR=m) 

allowing  control  transfer  on 
error  conditions.  If  an 
end-of-file  condition  is 
detected  and  END=n  is 
specified,  execution  continues 
at  statement  n.  If  a  hardware 
I/O  error  occurs  and  ERR=m  is 
specified,  execution  continues 
at  statement  m. 


G-9 


FORTRAN  Language  Summary 


RETURN 

RETURN 


Returns  control  to  the  calling 
program  from  the  current 
subprogram. 


REWIND 

REWIND  u 


STOP 

STOP 

STOP  display 


SUBROUTINE 

SUBROUTINE  name 

SUBROUTINE  name  ( varl , var2 , .  .  . ) 


Logical  unit  number  u  is 
repositioned  to  the  beginning 
of  the  currently  opened  file. 


Terminates  program  execution 
and  prints  the  octal  constant, 
Hollerith  constant,  or 
alphanumeric  literal  display, 
if  one  is  specified. 


Begins  a 

subprogram, 
program  name 
variable  names 


SUBROUTINE 
indicating  the 
and  any  dummy 
(var) . 


TYPE 

TYPE  f ,list 

Type  Declarations 


type  varl,var2 ,. . . ,vark 


Writes  output  on  logical  unit 
7  (TT:  is  default);  f  is  the 
format  statement  label  and 
list  is  an  optional  data  list. 


The  variable  names,  (var) ,  are 
assigned  the  specified  data 
type  in  the  program  unit, 
type  is  one  of: 


INTEGER(*2 ,*4) 
REAL ( *  4 , *  8 ) 
DOUBLE  PRECISION 
COMPLEX (* 8) 
LOGICAL ( *4, *1) 


The  optional  *  indicates  that 
an  explicit  length  is  to  be 
set  for  the  variable;  the 
number  that  follows  is  the 
length  in  bytes.  The  length 
must  be  one  of  the  permitted 
values  above. 
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WRITE 

Formatted 

WRITE  (u,f) 

WRITE  (u,f)  list 

Causes  one  or  more  logical 
records  containing  the  values 
of  the  variables  in  the  list 
to  be  written  onto  device  u 
according  to  the  format 
specification  f. 


Unformatted 

WRITE  (u) 

WRITE  (u) list 

Direct  Access 

WRITE  (u'r)  list 


Transfer  of  Control  on  Error 


Causes  one  logical  record 
containing  the  values  of  the 
variables  in  the  list  to  be 
written  onto  device  u. 


Causes  one  logical  record 
containing  the  values  of  the 
variables  in  the  list  to  be 
written  onto  record  r  of  the 
logical  unit  number  u. 


END=n 

ERR=m 

END=n,ERR=m  Optional  elements  in  the  WRITE 

statement  list  (e.g.,  WRITE 
u,f,  END=n ,  ERR=m)  allowing 
control  transfer  on  error 
conditions.  If  an  end-of-file 
condition  is  detected  and 
END=n  is  specified ,  execution 
continues  at  statement  n.  If  a 
hardware  I/O  error  occurs  and 
ERR=m  is  specified,  execution 
continues  at  statement  m. 


G.5  COMPILER  ERROR  DIAGNOSTICS 

The  RT-11  FORTRAN  Compiler,  while  reading  and  processing  the  FORTRAN 
source  program,  can  detect  syntax  errors  (or  errors  in  general  form) 
such  as  unmatched  parentheses,  illegal  characters,  unrecognizable  key 
words,  missing  or  illegal  statement  parameters.  The  number  of  errors 
detected  during  compilation  is  indicated  on  the  console  terminal  by 
the  message: 

ERRORS  DETECTED:  n 

The  next  three  sections  describe  the  initial  phase  and  secondary  phase 
error  diagnostics  and  the  fatal  FORTRAN  Compiler  error  diagnostics. 
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G. 5.1  Errors  Reported  by  the  Initial  Phase  of  the  Compiler 

These  errors  are  reported  in  the  source  program  listing;  they  are  not 
reported  if  a  source  listing  is  not  requested.  Only  errors  which 
cause  a  statement  to  be  aborted  are  tabulated  in  the  ERRORS  DETECTED 
count. 

The  error  diagnostics  are  printed  after  the  source  statement  to  which 
they  apply  (the  L  error  diagnostic  is  an  exception) .  The  general  form 
of  the  diagnostic  is  as  follows: 

******  c 

Where  c  is  a  code  letter  whose  meaning  is  described  below: 


Code  Letter  Description 

B  Columns  1-5  of  a  continuation  line  are  not  blank. 

(Columns  1-5  of  a  continuation  line  must  be  blank 
except  for  a  possible  'D'  in  column  l);the  columns 
are  ignored  and  compilation  continues. 

C  Illegal  continuation.  Comments  cannot  be 

continued  and  the  first  line  of  a  program  unit 
cannot  be  a  continuation  line.  The  line  is 
ignored  and  compilation  continues. 

E  Missing  END  statement.  An  END  statement  is 

supplied  by  the  Compiler  if  end-of-file  is 
encountered. 

H  Hollerith  string  or  quoted  literal  string  longer 

than  255  characters  or  longer  than  the  remainder 
of  the  statement.  The  statement  is  aborted. 

I  Non-FORTRAN  character  used.  The  line  contains  a 

character  that  is  not  in  the  FORTRAN  character  set 
and  is  not  in  a  Hollerith  string  or  comment  line. 
The  character  is  ignored  and  compilation 
continues . 

K  Illegal  statement  label  definition.  Illegal 

(non-numeric)  character  in  statement  label  field. 
The  illegal  statement  label  is  ignored  and 
compilation  continues. 

L  Line  too  long.  There  are  more  than  80  characters 

in  a  line;  this  diagnostic  is  issued  before  the 
line  containing  too  many  characters.  The  line  is 
truncated  to  80  characters  and  compilation 
continues . 

M  Multiply  defined  label.  The  label  is  ignored. 

P  Statement  contains  unbalanced  parentheses.  The 

statement  is  aborted. 

S  Syntax  error  (multiple  equal  signs,  etc.). 

Statement  not  of  the  general  FORTRAN  statement 
form.  The  statement  is  aborted. 
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U 


Statement  could  not  be  identified  as  any  legal 
FORTRAN  statement.  The  statement  is  aborted. 


G.5.2  Errors  Reported  by  Secondary  Phases  of  the  Compiler 

Those  Compiler  error  diagnostics  not  reported  by  the  initial  phase  of 
the  Compiler  will  appear  immediately  after  the  source  listing  and 
before  the  storage  map.  The  general  form  of  the  diagnostic  is: 

IN  LINE  nnnnn  MSG#m  text 

Where  nnnnn  is  the  internal  sequence  number  of  the  statement  in 

question,  m  is  an  integer  constant  specifying  the  error  number,  and 
text  is  a  short  description  of  the  error.  The  line  at  fault  is 
replaced  by  a  call  to  a  routine  which  generates  a  run-time  error  (see 

Section  G.5)  if  program  control  passes  through  the  statement.  All 

errors  reported  by  the  secondary  phase  of  the  compiler  are  tabulated 
in  the  ERRORS  DETECTED  count. 

The  notation  ****  signifies  that  a  particular  variable  name  or 

statement  label  will  appear  at  that  place  in  the  text. 


ADJUSTABLE  DIMENSIONS  ILLEGAL  FOR  ARRAY  **** 

All  arrays  must  be  dimensioned  with  integer  constants 
except  as  specified  in  the  RT-11  FORTRAN  COMPILER  AND 
OBJECT  TIME  SYSTEM  USER'S  MANUAL  (DEC-ll-LRFPA-A-D) . 

ARRAY  ****  HAS  TOO  MANY  DIMENSIONS 

An  array  can  have  up  to  seven  dimensions. 

ATTEMPT  TO  EXTEND  COMMON  BACKWARDS 

While  attempting  to  equivalence  arrays  in  COMMON,  an 
attempt  was  made  to  extend  COMMON  past  the  recognized 
beginning  of  COMMON  storage. 

COMMON  BLOCK  EXCEEDS  MAXIMUM  SIZE 

An  attempt  was  made  to  allocate  more  space  to  COMMON 
than  is  physically  addressable  (>32K  words). 

DANGLING  OPERATOR 

An  operator  etc.)  is  missing  an  operand. 

Example:  (I=J+). 

DEFECTIVE  DOTTED  KEYWORD 

A  dotted  relational  operator  was  not  recognized.  Also, 
possible  misuse  of  decimal  point. 

DO  TERMINATOR  ****  PRECEDES  DO  STATEMENT 

The  statement  specified  as  the  terminator  of  a  DO  loop 
must  come  after  the  DO  statement. 

EXPECTING  LEFT  PARENTHESIS  AFTER  **** 

An  array  name  or  function  name  reference  is  not 
followed  by  a  left  parenthesis. 

EXTRA  CHARACTERS  AT  END  OF  STATEMENT 

All  the  necessary  information  for  a  syntactically 
correct  FORTRAN  statement  has  been  found  on  this  line. 
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but  more  information  exists.  Possibly  due  to 
inadvertent  continuation  signal  on  next  line,  or  a 
missing  comma. 

FLOATING  CONSTANT  TOO  SMALL 

A  floating  constant  in  an  expression  is  too  close  to 
zero  to  be  represented  in  the  internal  format.  Use 
zero  if  possible. 

ILLEGAL  ADJACENT  OPERATOR 

Two  operators  (*,/,  logical  operators,  etc.)  are 
illegally  placed  next  to  each  other.  Example:  I/*J. 

ILLEGAL  ELEMENT  IN  I/O  LIST 

An  item,  expression,  or  implied  DO  specifier  in  an  I/O 
list  is  of  illegal  syntax. 

ILLEGAL  DO  STATEMENT  TERMINATOR  **** 

A  DO  statement  terminator  must  not  be  a  GO  TO, 
arithmetic  IF,  RETURN,  or  DO  statement  or  logical  IF 
containing  one  of  these  statements. 

ILLEGAL  STATEMENT  ON  LOGICAL  IF 

The  statement  contained  in  a  logical  IF  must  not  be 
another  logical  IF  or  DO  statement. 

ILLEGAL  TYPE  FOR  OPERATOR 

An  illegal  variable  type  has  been  used  with  an 
exponentiation  or  logical  operator. 

ILLEGAL  USAGE  OF  OR  MISSING  LEFT  PARENTHESIS 

A  left  parenthesis  was  required  but  not  found,  or  a 
variable  reference  or  constant  is  illegally  followed  by 
a  left  parenthesis. 

INTEGER  OVERFLOW 

An  integer  constant  or  expression  value  must  not  fall 
outside  the  range  -32767  to  +32767. 

INVALID  COMPLEX  CONSTANT 

A  complex  constant  has  been  improperly  formed. 

INVALID  DIMENSIONS  FOR  ARRAY**** 

An  attempt  was  made  while  dimensioning  an  array  to 
explicitly  specify  zero  as  one  of  the  dimensions. 

INVALID  DO  TERMINATOR  ORDERING  AT  LABEL  **** 

Do  loops  are  incorrectly  nested. 

INVALID  EQUIVALENCE 

Illegal  equivalence,  or  equivalence  that  is 

contradictory  to  a  previous  equivalence. 

INVALID  FORMAT  SPECIFIER 

A  format  specifier  is  not  the  label  of  a  FORMAT 
statement  or  an  array  name. 

INVALID  IMPLICIT  RANGE  SPECIFIER 

Illegal  implicit  range  specifier,  i.e.,  non-alphabetic 
specifier,  or  specifier  range  is  in  reverse  alphabetic 
order. 
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INVALID  LOGICAL  UNIT 

A  logical  unit  reference  must  be  an  integer  variable  or 
constant  in  the  range  1  to  99. 

INVALID  OCTAL  CONSTANT 

An  octal  constant  is  too  large  or  contains  a  digit 
other  them  0-7. 

INVALID  OPTIONAL  LENGTH  SPECIFIER 

A  data  type  declaration  optional  length  specifier  is 
illegal.  For  example,  REAL* 4  and  REAL* 8  are  legal,  but 
REAL*6  is  not. 

INVALID  RADIX50  CONSTANT 

Illegal  character  detected  in  a  RADIX50  constant. 
INVALID  RECORD  FORMAT 

The  third  parenthetical  argument  in  a  DEFINE  FILE 
statement  must  be  the  single  character  U. 

INVALID  STATEMENT  IN  BLOCK  DATA 

It  is  illegal  to  have  any  executable  or  FORMAT 
statements  in  a  BLOCK  DATA  Subprogram. 

INVALID  STATEMENT  LABEL  REFERENCE 

Reference  has  been  made  to  a  statement  number  that  is 
of  illegal  construction.  GO  TO  999999  is  illegal  since 
the  statement  number  is  too  long. 

INVALID  SUBROUTINE  OR  FUNCTION  NAME 

A  name  used  in  a  CALL  statement  or  function  reference 
is  not  valid.  Example:  use  of  an  array  name  in  a  CALL 
statement  subroutine  name  reference. 

INVALID  TARGET  FOR  ASSIGNMENT 

The  left  side  of  an  arithmetic  assignment  statement  is 
not  a  variable  name  or  array  element  reference. 

INVALID  TYPE  SPECIFIER 

An  unrecognizable  data  type  was  used. 

INVALID  USAGE  OF  FUNCTION  OR  SUBROUTINE  NAME 

A  function  name  cannot  appear  in  a  DIMENSION,  COMMON, 
DATA,  EQUIVALENCE,  or  Data  Type  Declaration  statement. 

INVALID  VARIABLE  NAME 

A  variable  name  is  missing,  contains  an  illegal 
character ,  or  does  not  begin  with  an  alphabetic 
character. 

LABEL  ON  DECLARATIVE  STATEMENT 

It  is  illegal  to  place  a  label  on  a  declarative 
statement. 

MISSING  ASSIGNMENT  OPERATOR 

The  first  operator  seen  in  an  arithmetic  assignment 
statement  was  not  an  equal  sign  (=).  Example:  I+J=K. 

MISSING  COMMA 

The  comma  delimiter  was  expected  but  was  not  found. 
See  the  section  of  the  FORTRAN  Reference  Manual  that 
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describes  the  general  form  of  the  statement  in 
question. 

MISSING  DELIMITER  IN  EXPRESSION 

Two  operands  have  been  placed  next  to  each  other  in  an 
expression,  with  no  operator  between  them. 

MISSING  LABEL 

A  statement  label  was  expected  but  not  found.  Example: 
ASSIGN  J  TO  I.  A  valid  statement  label  reference  should 
precede  ’TO'  but  does  not. 

MISSING  RIGHT  PARENTHESIS 

Expecting  a  right  parenthesis  but  one  was  not  found. 
Example:  READ(5,100,) .  The  first  non-blank  character 

after  the  format  reference  should  be  a  right 
parenthesis  but  is  not. 

MISSING  QUOTATION  MARK 

In  a  FIND  statement,  the  logical  unit  number  and  record 
number  must  be  separated  by  a  single  quotation  mark. 

MISSING  VARIABLE 

A  variable  was  expected  but  not  found.  Example: 
ASSIGN  100  TO  1.  A  variable  name  should  follow  the  'TO' 
but  does  not. 

MISSING  VARIABLE  OR  CONSTANT 

Looking  for  an  operand  (variable  or  constant)  but  found 
a  delimiter  (comma,  parenthesis,  etc.).  Example: 
WRITE ( ) .  A  unit  number  should  follow  the  open 
parenthesis,  but  a  delimiter  (close  parenthesis)  is 
encountered  instead. 

MODES  OF  VARIABLE  ****  AND  DATA  ITEM  DIFFER 

The  data  type  of  each  variable  and  its  associated  data 
list  item  must  agree  in  a  DATA  Statement. 

MULTIPLE  DECLARATION  FOR  VARIABLE  **** 

A  variable  cannot  appear  in  more  than  one  data  type 
declaration  statement  or  dimensioning  statement. 

NUMBER  IN  FORMAT  STATEMENT  NOT  IN  RANGE 

An  integer  constant  in  a  FORMAT  statement  is  greater 
than  255  or  is  zero. 

PARENTHESES  NESTED  TOO  DEEPLY 

Group  repeats  in  a  FORMAT  Statement  have  been  nested 
too  deeply. 

P-SCALE  FACTOR  NOT  IN  RANGE  -127  TO  +127 

P-scale  factors  must  fall  in  the  range  -127  to  +127. 

REFERENCE  TO  INCORRECT  TYPE  OF  LABEL  **** 

A  statement  label  reference  that  should  be  a  label  on  a 
FORMAT  statement  is  not  such  a  label,  or  a  statement 
label  reference  that  should  be  a  label  on  an  executable 
statement  is  not  such  a  label. 

REFERENCE  TO  UNDEFINED  STATEMENT  LABEL 

A  reference  has  been  made  to  a  statement  number  that 
has  not  been  defined  anywhere  in  the  program  unit. 
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STATEMENT  MUST  BE  UNLABELED 

A  DATA,  SUBROUTINE,  FUNCTION,  BLOCK  DATA,  arithmetic 
statement  function  definition,  or  declarative  statement 
must  not  be  labeled. 

STATEMENT  TOO  COMPLEX 

An  arithmetic  statement  function  has  more  than  10  dummy 
arguments.  Or  the  statement  is  too  long  to  compile. 
Break  it  up  into  2  or  more  smaller  statements. 

SUBROUTINE  OR  FUNCTION  STATEMENT  MUST  BE  FIRST 

A  SUBROUTINE,  FUNCTION  or  BLOCK  DATA  Statement,  if 
present,  must  be  the  first  statement  in  a  program  unit. 

SUBSCRIPT  OF  ARRAY  ****  NOT  IN  RANGE 

Array  subscripts  that  are  constants  or  constant 
expressions  are  checked  to  see  if  they  are  within  the 
bounds  of  the  array's  dimensions. 

SYNTAX  ERROR 

Check  the  general  form  of  the  statement  with  the 
general  form  outlined  in  the  FORTRAN  LANGUAGE  REFERENCE 
MANUAL  section  that  describes  that  type  of  statement. 

TARGET  MUST  BE  ARRAY 

The  third  argument  in  an  ENCODE  or  DECODE  statement 
must  be  an  array  name. 

SYNTAX  ERROR  IN  INTEGER  OR  FLOATING  CONSTANT 

An  integer  or  floating  constant  has  been  incorrectly 
formed.  For  example,  1.23.4  is  an  illegal  floating 
constant  because  it  contains  two  decimal  points. 

UNLABELED  FORMAT  STATEMENT 

All  FORMAT  Statements  must  be  labeled. 

USAGE  OF  VARIABLE  ****  INVALID 

An  attempt  was  made  to  EXTERNAL  a  common  variable,  an 
array  variable,  or  a  dummy  argument  or  an  attempt  was 
made  to  place  in  COMMON  a  dummy  argument  or  external 
name. 

VARIABLE  ****  INVALID  IN  ADJUSTABLE  DIMENSION 

A  variable  used  as  an  adjustable  dimension  must  be  an 
integer  dummy  argument  in  the  subprogram  unit. 

WRONG  NUMBER  OF  SUBSCRIPTS  FOR  ARRAY  **** 

An  array  reference  does  not  have  the  same  number  of 
subscripts  as  specified  when  the  array  was  dimensioned. 


G.5.3  Warning  Diagnostics 

Warning  diagnostics  report  conditions  which  are  not  true  error 
conditions,  but  which  may  be  potentially  dangerous  at  execution  time, 
or  which  may  present  compatibility  problems  with  FORTRAN  Compilers 
running  on  other  PDP-11  Operating  Systems.  The  warning  diagnostics 
are  normally  suppressed,  but  may  be  enabled  by  use  of  the  /W  Compiler 
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switch.  The  form  and  placement  of  the  warning  diagnostics  are  the 
same  as  those  for  the  secondary  phase  error  diagnostics  except  that 
the  line  number  reference  is  replaced  with  [WARNING] .  A  listing  of  the 
warning  diagnostics  follows : 

ADJUSTABLE  DIMENSIONS  ILLEGAL  FOR  ARRAY  **** 

Adjustable  arrays  must  be  a  dummy  argument  in  a 
subprogram,  and  the  adjustable  dimensions  must  be 
integer  dummy  arguments  in  the  subprogram.  Any 
variation  from  this  rule  will  cause  a  dimension  of  1  to 
be  used  and  this  warning  message  to  be  issued. 

NON-STANDARD  STATEMENT  ORDERING 

Although  the  RT-11  FORTRAN  Compiler  has 
less-restrictive  statement-ordering  requirements  than 
those  outlined  in  chapter  7  of  the  PDP-11  FORTRAN 
LANGUAGE  REFERENCE  MANUAL,  non-adherence  to  the 
stricter  requirements  may  cause  error  conditions  on 
other  FORTRAN  Compilers. 

VARIABLE  ****  IS  NOT  WORD  ALIGNED 

Placing  a  non-LOGICAL*l  variable  or  array  after  a 
L0GICAL*1  variable  or  array  in  COMMON  or  equivalencing 
non-LOGICAL*l  variables  or  arrays  to  logical* 1 
variables  or  arrays  may  cause  this  condition.  An 
attempt  to  reference  the  variable  at  runtime  will  cause 
an  error  condition. 

VARIABLE  ****  NAME  EXCEEDS  SIX  CHARACTERS 

A  variable  name  of  more  them  six  characters  was 
specified.  The  first  six  characters  were  used  as  the 
true  variable  name.  Other  FORTRAN  Compilers  may  treat 
this  as  an  error  condition. 


G.5.4  Fatal  Compiler  Error  Diagnostics 

These  diagnostics,  which  are  sent  directly  to  the  terminal,  report 
hardware  error  conditions  and  conditions  which  may  require  rewriting 
of  the  source  program.  The  form  of  the  diagnostic  is  s 

FATAL  ERROR  n 

where  n  is  one  of  the  following  error  codes : 

Code  Meaning 

C  Constant  subscript  overflow.  Too  many  constant 
subscripts  have  been  employed  in  a  statement. 

SOLUTION  -  simplify  the  statement. 

0  Unrecoverable  error  occurred  while  the  Compiler  was 
writing  the  object  file  (.OBJ).  Possibly,  insufficient 
output  file  space. 

SOLUTION  -  rectify  hardware  problem,  or  allow  more 
space  for  output. 
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P  Optimizer  push  down  overflow  -  statement  too  complex, 
or  too  many  common  subexpressions  occurred  in  one  basic 
block  of  a  program. 

SOLUTION  -  simplify  complex  statements. 

R  Unrecoverable  hardware  error  occurred  while  the 
Compiler  was  reading  source  file. 

SOLUTION  -  rectify  hardware  problem. 

S  Subexpression  stack  overflow  -  statement  too  complex. 

SOLUTION  -  simplify  complex  statements. 

T  Memory  Overflow. 

SOLUTION  -  break  up  program  into  subprograms  or  compile 
on  larger  machine. 

W  Unrecoverable  error  occurred  while  the  Compiler  was 
writing  listing  file.  Possibly,  listing  file  space  is 
not  large  enough. 

SOLUTION  -  rectify  hardware  problem,  or  allow  more 
space  for  listing  file. 

Y  Code  generation  stack  overflow  -  statement  too  complex. 

SOLUTION  -  simplify  complex  statements. 

Z  Compiler  error. 

SOLUTION  -  report  this  error  to  your  local  software 
support  representative.  Please  include  program 
listing. 


G.6  OBJECT  TIME  SYSTEM  ERROR  DIAGNOSTICS 

The  Object  Time  System  detects  certain  I/O,  arithmetic,  and  system 
failure  error  conditions  and  reports  them  on  the  user  terminal.  These 
error  diagnostics  are  printed  in  either  a  long  or  a  short  form. 

The  short  form  of  the  message  appears  as : 

?ERR  nn 

where  nn  is  a  decimal  error-identification  number.  The  long  form  of 
the  message  appears  as: 

?ERR  nn  text 

where  nn  is  a  decimal  error-identification  number  and  text  is  a  short 
error  description. 

The  default  message  length  is  long.  The  short  message  error  module 
may  be  included  with  the  program  by  using  the  /I  Linker  switch  (see 
Chapter  6) .  The  module  named  $SHORT  should  be  included  from  the 
FORTRAN  library. 
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There  are  four  classes  of  OTS  error  conditions.  Each  error  condition 
is  assigned  to  one  of  these  classes.  The  error  condition 
classification  for  the  error  codes  1-16  can  be  changed  by  using  the 
System  Subroutine  SETERR.  (Refer  to  DEC-ll-LRFPA-A-D. )  Error  codes  0 
and  20-66  should  not  be  changed  from  their  FATAL  classification  or 
undeterminable  results  will  occur.  The  classifications  are: 


IGNORE 

The  error  is  detected  but  no  error  message 
sent  to  the  terminal.  Execution  continues. 

is 

WARNING 

The  error 
execution 

message  is  sent 
continues . 

to 

the 

terminal 

and 

FATAL 

The  error 
execution 

message  is  sent 
is  terminated. 

to 

the 

terminal 

and 

COUNT sn 

The  error 

message  is  sent 

to 

the 

terminal 

and 

execution  continues  until  the  nth  occurrence  of 
the  error,  at  which  time  the  error  will  be 
treated  as  FATAL. 


If  a  program  is  terminated  by  a  fatal  error  condition,  active  files 
are  closed. 

The  OTS  error  diagnostics  are  listed  below  along  with  the  error  type 
and  a  brief  explanation  where  necessary. 


Error 

number 


0 


1 


2 


3 


4 


5 


Error 

type 

FATAL 

FATAL 


FATAL 


FATAL 


Message 


NON-FORTRAN  ERROR  CALL 

A  TRAP  has  occurred  with  an  unrecognizable 
error  code, 

INTEGER  OVERFLOW 

During  an  arithmetic  operation ,  an 
integer's  value  has  exceeded  32767  in 
magnitude, 

INTEGER  ZERO  DIVIDE 

During  an  integer  mode  arithmetic 
operation  an  attempt  was  made  to  divide  by 
zero. 

COMPILER  GENERATED  ERROR 

An  attempt  is  made  to  execute  a  FORTRAN 
statement  in  which  the  compiler  has 
detected  errors. 


WARNING  COMPUTED  GO  TO  OUT  OF  RANGE 

The  integer  variable  or  expression  in  a 
computed  GO  TO  statement  was  less  than  1 
or  greater  than  the  number  of  statement 
label  references  in  the  list.  Control  is 
passed  to  the  next  executable  statement. 

COUNT: 3  INPUT  CONVERSION  ERROR 

During  a  formatted  input  operation  an 
illegal  character  was  detected  in  an  input 
field.  A  value  of  0  is  returned. 
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Error 

number 

Error 

type 

Message 

6 

IGNORE 

OUTPUT  CONVERSION  ERROR 

During  a  formatted  output  operation  the 
value  of  a  particular  number  could  not  be 
output  in  the  specified  field  length 
without  loss  of  significant  digits.  The 
field  is  filled  with  *'s. 

10 

COUNT : 3 

FLOATING  OVERFLOW 

During  an  arithmetic  operation  a  real 
value  has  exceeded  the  largest 
representable  real  number.  A  value  of  0 
is  returned. 

11 

IGNORE 

FLOATING  UNDERFLOW 

During  an  arithmetic  operation  a  real 
value  has  become  less  than  the  smallest 
representable  real  number,  and  has  been 
replaced  with  a  value  of  zero. 

12 

FATAL 

FLOATING  ZERO  DIVIDE 

During  a  real  mode  arithmetic  operation  an 
attempt  was  made  to  divide  by  zero. 

13 

COUNT: 3 

SQRT  OF  NEGATIVE  NUMBER 

An  attempt  was  made  to  take  the  square 
root  of  a  negative  number.  The  result  is 
replaced  by  zero. 

14 

FATAL 

UNDEFINED  EXPONENTIATION  OPERATION 

An  attempt  was  made  to  perform  an  illegal 
exponentiation  operation.  For  example 
-3.**, 5  is  illegal  because  the  result 
would  be  an  imaginary  number. 

15 

FATAL 

LOG  OF  NEGATIVE  NUMBER 

An  attempt  was  made  to  take  the  logarithm 
of  a  negative  number. 

16 

FATAL 

WRONG  NUMBER  OF  ARGUMENTS 

One  of  the  FORTRAN  Library  functions,  or 
System  Subroutines  which  checks  for  such 
an  occurrence,  has  been  called  with  an 
improper  number  of  arguments. 

The  following  error  diagnostics  should  not  be  changed  from  the  FATAL 
classification  by  use  of  the  System  Subroutine  SETERR: 

20 

FATAL 

INVALID  CHANNEL  NUMBER 

An  illegal  logical  unit  number  has  been 
specified  in  an  I/O  statement.  A  logical 
unit  number  must  be  an  integer  between  1 
and  99. 

21 

FATAL 

NO  AVAILABLE  CHANNELS 

An  attempt  was  made  to  have  too  many 
devices  simultaneously  open  for  I/O,  The 
maximum  number  of  active  channels  is  six 
by  default ,  but  this  number  may  be  changed 
at  compile  time. 
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22  FATAL 


23  FATAL 


24  FATAL 


25  FATAL 


26  FATAL 


27 

28 

29 

30 

31 

32 

33 


FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 


INPUT  RECORD  TOO  LONG 

During  an  input  operation  a  record  was 
encountered  that  was  longer  than  the 
maximum  record  length.  The  default 
maximum  record  length  is  133  (decimal) 
bytes,  but  this  maximum  may  be  altered  at 
compile  time, 

HARDWARE  I/O  ERROR 

A  hardware  error  has  been  detected  during 
an  I/O  operation, 

ATTEMPT  TO  READ/WRITE  PAST  END  OF  FILE 
If  this  occurs  during  a  WRITE,  more  space 
is  needed  to  contain  the  output  file, 

ATTEMPT  TO  READ  AFTER  WRITE 
An  attempt  was  made  to  read  after  writing 
on  a  file,  A  WRITE  must  be  followed  by  a 
REWIND  or  BACKSPACE  before  a  read 
operation  can  be  performed, 

RECURSIVE  I/O  NOT  ALLOWED 

An  expression  in  the  I/O  list  of  a  WRITE 
statement  has  caused  initiation  of  another 
READ  or  WRITE  operation.  This  can  happen 
if  a  FUNCTION  that  performs  I/O  is 
referenced  in  an  expression  in  a  WRITE 
statement  I/O  list. 

ATTEMPT  TO  USE  DEVICE  NOT  IN  SYSTEM 

OPEN  FAILED  FOR  FILE 
A  file  could  not  be  found. 

NO  ROOM  FOR  DEVICE  HANDLER 

There  is  not  enough  free  memory  left  to 

accommodate  a  specific  device  handler. 

NO  ROOM  FOR  BUFFERS 

There  is  not  enough  free  memory  left  to 
set  up  required  I/O  buffers. 

NO  AVAILABLE  RT-11  CHANNEL 
More  than  the  maximum  number  of  RT-11 
channels,  15,  were  requested  to  be 
simultaneously  opened  for  I/O. 

FMTD-UNFMTD- RANDOM  I/O  TO  SAME  FILE 
An  attempt  was  made  to  perform  any 
combination  of  formatted,  unformatted,  or 
random  access  I/O  to  the  same  file. 

ATTEMPT  TO  READ  PAST  END  OF  RECORD 
An  attempt  was  made  to  read  a  larger 
record  than  actually  exists  in  a  file. 
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34 


35 

36 

37 


38 


39 


40 


41 


42 


43 


44 


45 


46 


FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 

FATAL 


UNFMTD  I/O  TO  TTY  OR  LPT 

An  attempt  was  made  to  perform  an 
unformatted  write  operation  on  the 
terminal  or  line  printer. 

ATTEMPT  TO  OUTPUT  TO  READ  ONLY  FILE 

BAD  FILE  SPECIFICATION  STRING 

RANDOM  ACCESS  READ/WRITE  BEFORE  DEFINE 
FILE 

A  random  access  READ  or  WRITE  operation 
was  attempted  before  a  DEFINE  FILE  was 
performed. 

RANDOM  I/O  NOT  ALLOWED  ON  TTY  OR  LPT 
Random  access  I/O  was  illegally  attempted 
on  the  terminal  or  line  printer. 

RECORD  LARGER  THAN  RECORD  SIZE  IN  DEFINE  FILE 
A  record  was  encountered  that  was  larger 
than  that  specified  in  the  DEFINE  FILE 
statement  for  a  random  access  file. 

REQUEST  FOR  A  BLOCK  LARGER  THAN  65535 
An  attempt  was  made  to  reference  an 
absolute  block  address  greater  than  65535. 

DEFINE  FILE  ATTEMPTED  ON  AN  OPEN  UNIT 
An  open  file  must  be  closed  before  another 
DEFINE  FILE  can  be  performed  on  that  unit. 

MEMORY  OVERFLOW  COMPILING  OBJECT  TIME  FORMAT 
The  OTS  has  run  out  of  free  memory  while 
scanning  an  array  format  that  was 
generated  at  run  time. 

SYNTAX  ERROR  IN  OBJECT  TIME  FORMAT 
A  syntax  error  was  encountered  while  the 
OTS  was  scanning  an  array  format  that  was 
generated  at  run  time. 

2ND  RECORD  REQUEST  IN  ENCODE/DECODE 
ENCODE  and  DECODE  will  operate  only  on  a 
single  record  at  a  time. 

INCOMPATIBLE  VARIABLE  AND  FORMAT  TYPES 
An  attempt  was  made  to  output  a  real 
variable  with  an  integer  field  descriptor 
or  an  integer  variable  with  a  real  field 
descriptor. 

INFINITE  FORMAT  LOOP 

The  format  associated  with  an  I/O 
statement  that  includes  an  I/O  list  has  no 
field  descriptors  to  use  in  transferring 
those  variables. 
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47 


60 


61 


62 


63 


FATAL  ATTEMPT  TO  STORE  OUTSIDE  PARTITION 

In  an  attempt  to  store  data  into  a 
subscripted  variable,  the  address 
calculated  for  the  array  element  in 
question  does  not  lie  within  the  section 
of  memory  allocated  to  the  job.  The 
subscript  in  question  is  out-of-bounds. 
(Message  is  issued  only  when 
bounds-checking  modules  have  been 
installed  in  FORLIB.) 

FATAL  STACK  OVERFLOWED 

The  hardware  stack  has  overflowed.  Proper 
Traceback  will  be  impaired. 

FATAL  ILLEGAL  MEMORY  REFERENCE 

This  may  be  any  type  of  BUS  error,  most 
probably  an  illegal  memory  address 
reference. 

FATAL  FORTRAN  START  FAIL 

The  program  has  been  loaded  into  memory 
but  there  was  not  enough  free  memory 
remaining  for  the  OTS  to  initialize  work 
space  and  buffers. 

FATAL  ILLEGAL  INSTRUCTION 

The  program  has  attempted  to  execute  an 
illegal  instruction,  e.g.,  floating  point 
arithmetic  instruction  on  a  machine  with 
no  floating  point  hardware. 
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H.l  F/B  PROGRAMMING  IN  RT-11,  VERSION  2 

Certain  programming  conventions  must  be  observed  in  RT-11,  Version  2 
which  were  not  required  in  Version  1.  These  conventions  are  necessary 
to  permit  interrupt  routines  to  function  properly  while  running  two 
jobs  in  the  F/B  environment.  All  Version  2  device  handlers  follow 
these  conventions;  the  user  is  urged  to  consult  the  listings  of  the 
example  handlers  (Section  H.3)  as  they  illustrate  some  of  the 


NOTE 

Device  handlers  distributed  with  RT-11, 
Version  1,  will  not  work  properly  with 
Version  2.  Also,  any  user-written  device 
handlers  should  be  re-written  to  comply 
with  the  Version  2  conditions. 
Instructions  for  interfacing  new 
handlers  to  RT-11  are  provided  in  the 
RT-11  SOFTWARE  SUPPORT  MANUAL. 
(DEC— 11— ORPGA— B— D) .  Section  H.2 
describes  Version  2  device  handlers. 


The  procedures  described  in  this  appendix  are  necessary  and  must  be 
followed  to. prevent  system  failures  when  jobs  are  running  under  RT-11. 
If  at  any  time  a  program  which  services  its  own  interrupts  (and  does 
not  follow  the  guidelines  described  here)  is  run  with  another  job,  the 
system  may  malfunction.  Therefore,  it  is  required  that  all  programs 
follow  the  procedures  that  are  indicated  here. 


H.1.1  Interrupt  Priorities 

The  status  word  for  each  interrupt  vector  should  be  set  such  that  when 
an  interrupt  occurs,  the  processor  takes  it  at  level  7.  Thus,  a  device 
which  has  its  vectors  at  70  and  72  has  location  70  set  to  its  service 
routine;  location  72  contains  340.  The  340  causes  the  service  routine 
to  be  entered  with  the  processor  set  to  inhibit  any  device  interrupts. 


H-l 


F/B  Programming  and  Device  Handlers 


H.1.2  Interrupt  Service  Routine 

If  the  conventions  outlined  in  Section  H.1.1  are  followed,  when 
interrupt  occurs,  the  processor  priority  will  be  7.  The  first  task  of 
the  interrupt  service  routine  is  to  lower  the  processor  priority  to 
the  correct  value.  This  can  be  done  using  the  .INTEN  macro  call.  The 
call  is: 


or 


.INTEN  .priority 
. INTEN  . priority , . pic 


The  .INTEN  call  is  explained  in  Chapter  9,  Programmed  Requests.  On 
return  from  the  .INTEN  call,  the  processor  priority  is  set  properly; 
registers  4  and  5  have  been  saved  and  can  be  used  without  the 
necessity  of  saving  them  again. 

For  example,  a  user  device  interrupts  at  processor  priority  5: 

DEVPRI=5 

DEVINT:  .INTEN  DEVPRI  ;NOTE,  NOT  #DEVPRI 


RTS  PC 


H.1.3  Return  from  Interrupt  Service 

When  an  interrupt  has  been  serviced ,  instead  of  issuing  an  RTI  to 
return  from  the  interrupt,  the  routine  must  exit  with  an  RTS  PC.  This 
RTS  PC  returns  control  to  the  monitor,  which  then  restores  registers  4 
and  5,  and  executes  the  RTI. 

When  a  device  handler  has  completed  a  transfer  and  is  ready  to  return 
to  the  monitor  via  the  internal  monitor  completion  address.  R4  must 
be  pointing  to  the  fifth  word  of  the  handler.  It  is  no  longer 
necessary  to  have  RO  and  R3  on  the  stack,  as  it  was  in  Version  1.  The 
user  is  urged  to  consult  the  example  handlers  at  the  end  of  this 
section,  which  explains  the  operation  of  the  sample  handlers. 


H.1.4  Issuing  Programmed  Requests  at  the  Interrupt  Level 

Programmed  requests  from  interrupt  routines  must  be  preceded  by  a 
.SYNCH  call.  This  ensures  that  the  proper  job  is  running  when  the 
programmed  request  is  issued.  The  .SYNCH  call  assumes  that  nothing 
has  been  pushed  onto  the  stack  by  the  user  program  between  the  .INTEN 
call  and  the  .SYNCH  call.  On  successful  completion  of  a  .SYNCH,  RO 
and  Rl  have  been  saved  and  are  free  to  be  used.  R4  and  R5  are  no 
longer  free,  and  should  be  saved  and  restored  if  they  are  to  be  used. 
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H.1.5  Setting  Up  Interrupt  Vectors 

Devices  for  which  no  RT-11  handler  exists  must  be  serviced  by  the  user 
program.  For  example,  no  LPS  device  handler  exists;  to  use  an  LPS, 
the  user  must  write  his  own  interrupt  service  routine.  It  is  the 
responsibility  of  the  program  to  set  up  the  vector  for  devices  such  as 
this.  The  recommended  procedure  is  not  to  simply  move  the  service 
routine  address  and  340  into  the  desired  vector;  rather,  this 
operation  must  be  preceded  by  a  .PROTECT  macro  call.  The  .PROTECT 
ensures  that  neither  the  other  job  nor  the  monitor  already  has  control 
of  that  device.  If  the  .PROTECT  is  successful,  the  vector  can  be 
initialized. 


H.1.6  Using  .ASECT  Directives 

With  some  exceptions,  user  programs  should  not  contain  .ASECT 
directives.  The  Linker  does  not  allow  .ASECTs  above  1000  when  the  /R 
switch  is  used;  in  general  all  .ASECTs  below  1000  are  ignored.  The 
exceptions  ares 


40 

1  word 

program  start  address 

42 

1  word 

stack  start  address 

44 

1  word 

job  status  word 

46 

1  word 

USR  swap  address 

34,36 

2  words 

TRAP  instruction  vector 

.ASECTs  may  be  used  to  initialize  any  of  the  above  locations.  To 
initialize  any  other  locations  between  0-777,  the  user  should  first 
.PROTECT  the  appropriate  words,  and  then  move  the  correct  values  into 
place • 

A  job  which  contains  overlays  cannot  have  any  .ASECTs  at  all, 
including  those  listed  above.  If  overlays  are  to  be  used,  the  program 
start  address  should  be  set  up  as  the  argument  for  the  .END  statement; 
the  other  values  can  be  initialized  when  the  program  is  initiated. 

Since  .ASECTs  into  device  vectors  are  not  permitted,  the  user  program 
must  initialize  vectors  at  runtime.  To  do  this,  execute  a  .PROTECT 
for  the  specified  vector.  If  the  .PROTECT  is  successful,  it  is  safe 
to  move  values  into  the  vectors.  If  the  .PROTECT  request  fails,  it  is 
an  indication  that  the  vector  is  already  in  use  by  another  job  and 
that  it  is  not  safe  to  initialize  the  vector. 


H.1.7  Using  .SETTOP 

Proper  use  of  .SETTOP  is  vital  to  preserve  system  integrity.  Since 
RT-11  employs  no  hardware  memory  protection,  the  user  must  at  all 
times  observe  the  value  returned  in  R0  from  a  .SETTOP  request.  It 
must  never  be  assumed  that  the  value  requested  by  the  program  is  the 
value  returned  by  .SETTOP. 
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H.2  DEVICE  HANDLERS 

This  section  deals  with  the  device  handlers  which  are  part  of  the 
RT-11  System,  Version  2.  Any  device  dependent  information  or  general 
information  required  by  the  user  is  contained  here.  No  mention  of  a 
handler  implies  that  no  special  conditions  must  be  met  to  use  that 
device  (all  disks  and  DEC tape  are  in  this  category,  and  therefore  are 
not  covered  here) . 


Differences  Between  VI  and  V2  Device  Handlers 

User-written  device  handlers  must,  in  all  cases,  conform  to  the 
standard  practices  for  Version  2.  Since  the  last  word  of  a  device 
handler  is  used  by  the  monitor,  the  user  should  be  sure  to  include  one 
extra  word  at  the  end  of  his  program  when  indicating  the  size  of  the 
handler. 

The  differences  between  Version  1  and  Version  2  handlers  include  the 
following; 

A.  Header  Words 

In  Version  1  handlers,  the  third  header  word  was  taken  to  be 
the  priority  at  which  the  device  interrupt  was  taken.  In 
Version  2,  this  word  should  be  340,  indicating  that  the 
interrupt  should  be  taken  at  priority  level  7. 

B.  Entry  Conditions 

It  is  not  necessary  to  save/restore  registers  when  the 
handler  is  first  entered,  although  to  do  so  is  not  harmful. 
In  Version  1,  it  was  necessary  to  preserve  R5  on  first 
entering  the  handler. 

C.  Interrupt  Handling 

When  an  interrupt  occurs.  Version  2  handlers  must  execute  an 
.INTEN  request  or  its  equivalent.  (This  was  not  necessary  in 
Version  1.)  On  return  from  the  .INTEN,  R4  and  R5  may  be  used 
as  scratch  registers.  Device  handlers  may  not  do  EMT 
requests  without  executing  a  .SYNCH  request.  (Refer  to 
Chapter  9  for  explanations  of  .INTEN  and  .SYNCH.) 

The  handler  must  return  from  an  interrupt  via  an  RTS  PC 
rather  than  an  RTI ,  as  in  Version  1.  The  .INTEN  request 
essentially  reenters  the  handler  via  a  JSR  PC,  and  thus  the 
RTS  PC  returns  control  to  the  monitor,  which  executes  the  RTI 
when  appropriate. 

When  the  transfer  is  complete,  the  handler  must  exit  to  the 
monitor  to  terminate  the  transfer  and/or  enter  a  completion 
routine.  When  return  is  made  to  the  monitor,  R4  should  point 
to  the  fifth  word  of  the  handler. 

The  user  is  urged  to  refer  to  the  example  handlers  enclosed. 
The  same  general  techniques  can  be  used  to  interface  user 
device  handlers. 
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H.2.1  PR  (High-Speed  Paper  Tape  Reader) 

Unlike  the  PR  handler  for  Version  1 ,  the  Version  2  PR  handler  does  not 
print  a  t  on  the  terminal  when  it  is  entered  for  the  first  time.  The 
tape  must  be  in  the  reader  when  the  command  is  issued,  or  an  input 
error  occurs.  This  prohibits  any  two-pass  operations  from  being  done 
using  PR.  For  example,  linking  and  assembling  from  PR  will  not  work 
properly;  an  input  error  will  occur  when  the  second  pass  is 
initiated.  The  correct  (and  recommended)  procedure  is  to  use  PIP  to 
transfer  the  paper  tape  to  disk  or  DEC tape,  and  then  perform  the 
operation  on  the  transferred  file. 


H.2.2  TT  (Handler  for  Console  Terminal) 

The  console  terminal  may  be  used  as  a  peripheral  device  by  using  the 
TT  handler.  Note  that: 


1. 

2. 

3. 

4. 


5. 


6. 


A  t  is  typed  when  the  handler  is  ready  for  input. 

CTRL  Z  can  be  used  to  specify  the  end  of  input  to  TT.  No 
carriage  return  is  required  after  the  CTRL  Z.  If  CTRL  Z  is 
not  typed,  the  TT  handler  accepts  characters  until  the  word 
count  of  the  input  request  is  satisfied. 

CTRL  0,  struck  while  output  is  directed  to  TT,  causes  an 
entire  output  buffer  to  be  ignored  on  output.  This  is 
somewhat  different  than  the  normal  action  of  CTRL  0  while  at 
the  console. 

A  single  CTRL  C  struck  while  typing  input  to  TT  causes  a 
return  to  the  monitor.  If  output  is  directed  to  TT,  a  double 
CTRL  C  is  required  to  return  to  the  monitor  if  F/B  is 
running.  If  the  S/J  monitor  is  running,  only  a  single  CTRL  C 
is  required  to  terminate  output. 

The  TT  handler  can  be  in  use  for  only  one  job  (foreground  or 
background)  at  a  time,  and  for  only  one  function  (input  or 
output)  at  a  time.  The  terminal  communication  for  the  job 
not  using  TT  is  not  affected  at  all. 

The  user  may  type  ahead  to  TT;  the  input  ring  buffer  is 
emptied  before  the  keyboard  is  referenced.  The  terminating 
CTRL  Z  may  also  be  typed  ahead. 


7. 


8. 


If  the  main  line  code  of  a  job  is  using  TT  for  input,  and  a 
completion  routine  does  a  .TTYIN,  typed  characters  will  be 
passed  unpredictably  to  the  .TTYIN  and  TT.  Therefore,  this 
should  not  be  done. 

If  a  job  sends  a  buffer  to  TT  for  output  and  then  does  a 
.TTYOUT  or  a  .PRINT,  the  output  from  the  latter  is  delayed 
until  the  handler  completes  its  transfer.  If  a  TT  output 
operation  is  started  when  the  monitor's  terminal  output  ring 
buffer  is  not  empty  (i.e.,  before  the  print-ahead  is 
complete) ,  the  handler  supersedes  the  ring  buffer  until  its 
transfer  is  complete. 
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H.2.3  CR  (Card  Readers) 

The  card  reader  handler  can  transfer  data  either  as  ASCII  characters 
in  DEC  026  or  DEC  029  card  codes  (Section  H.4) ,  or  as  column  images 
controlled  by  the  SET  command  (see  Chapter  2) .  In  ASCII  mode  (SET  CR 
NOIMAGE) ,  invalid  punch  combinations  are  decoded  as  the  error 
character  134 (octal) —backs lash.  In  IMAGE  mode,  no  punch  combination 
is  invalid;  each  column  is  read  as  12  bits  of  data  right- justified  in 
one  word  of  the  input  buffer.  The  handler  continues  reading  until  the 
transfer  word  count  is  satisfied  or  until  a  standard  end-of-file  card 
is  encountered  (12-11-0-1-6-7-8-9  punch  in  column  1;  the  rest  of  the 
card  is  arbitrary).  On  end-of-file,  the  buffer  is  filled  with  zeroes 
and  the  request  terminates  successfully;  the  next  input  request  from 
the  card  reader  gives  an  end-of— file  error.  Note  that  if  the  transfer 
count  is  satisfied  at  a  point  which  is  not  a  card  boundary,  the  next 
request  continues  from  the  middle  of  the  card  with  no  loss  of 
information.  If  the  input  hopper  is  emptied  before  the  transfer 
request  is  complete,  the  handler  will  loop  until  the  hopper  is 
reloaded  and  the  "START"  button  on  the  reader  is  pressed  again.  The 
transfer  will  then  continue  until  completion  or  until  another  hopper 
empty  condition  exists.  End-of-file  is  not  reported  on  the  hopper 
empty  condition.  The  handler  will  loop  if  the  hopper  empties  during 
the  transfer  regardless  of  the  status  of  the  SET  CR  HANG/NOHANG 
option.  No  special  action  is  required  to  use  the  card  reader  handler 
with  the  CM- 11  mark  sense  card  reader.  The  program  must  be  aware  of 
the  fact  that  only  56  columns  per  card  will  be  transferred  if  NOTRIM 
is  in  effect. 


H.2.4  MT/CT  (Magtape  (TU10/TM11)  and  Cassette  (TA11)) 

These  devices  are  new  to  RT-11  (Version  2)  and  have  a  file  structure 
which  differs  from  the  common  RT-11  structure.  Each  handler  is 
capable  of  entirely  supporting  its  own  file  structure  and  of  allowing 
users  full  access  to  the  devices  without  being  totally  familiar 

with  them. 


H.2.4.1  General  Characteristics  -  Both  magtape  and  cassette  can 
operate  in  two  possible  modes:  "hardware"  mode  and  "software  mode. 
These  names  refer  to  the  type  of  operation  which  can  be  performed  on 
the  device  at  a  given  time.  Software  mode  is  the  normal  mode  of 
operation  and  the  mode  used  when  accessing  the  device  through  any  of 
the  RT— 11  system  programs.  In  software  mode,  the  handler 
automatically  attends  to  file  headers  and  uses  a  fixed  record  length 
to  transfer  data  (256-word  for  magtape;  64-word  for  cassette). 

Hardware  mode  allows  the  user  to  read  or  write  any  format  desired, 
using  any  record  size.  In  this  mode,  the  word  count  is  taken  as  the 
physical  record  size. 

When  the  handlers  are  initially  loaded  by  either  the  .FETCH  programmed 
request  or  the  .LOAD  command,  only  software  functions  are  permitted. 
To  switch  from  software  to  hardware  mode,  either  a  rewind  or  a 
non-file  structured  lookup  must  be  performed.  (A  non-file  structured 
lookup  is  a  lookup  in  which  the  first  word  of  the  filename  is  null.) 
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In  software  mode,  the  following  functions  are  permitted: 

Open  new  file  for  output 

Open  existing  file  for  input  and/or  output 

Delete  an  existing  file  on  the  device 

Close  a  file  which  was  opened  with  ENTER  or  LOOKUP 

Perform  data  transfer  requests 

LJ°KUP'  and  ?ELETE,  an  optional  file  count  parameter  can  be 
follows t  f°r  USS  Wlth  magtape  or  cassette.  its  meaning  is  as 


ENTER 

LOOKUP 

DELETE 

CLOSE 

READ/WRITE  - 


Count  Argument 
=0 
>0 


Meaning 


A  rewind  is  done  before  the  operation. 

No  rewind  is  done.  The  value  of  the  count  is 
taken  as  a  limit  of  how  many  files  to  skip  before 
performing  the  operation  (e.g.,  a  count  of  2  will 
skip  over,  at  most,  one  file.  A  count  of  1  will 
not  skip  at  all) . 

A  rewind  is  done.  The  complement  of  the  switch 
value  is  then  used  as  the  limit. 

o5^!^le^ndicated  in  the  recIuest  is  located  before  the  limit  is 
exhausted,  the  search  succeeds  at  that  point. 

As  an  example,  consider: 


<0 


.LOOKUP 

•  AREA#  #0,  #F 

BCS 

• 

A 1 

AREA: 

• 

•  BLKW 

10. 

PTR: 

.RAD50 

/MT0/ 

•RAD50 

/EXAMPLMAC/ 

In  this  case,  the  file  count  argument  is  +5,  indicating  that  no  rewind 

fpy?MPT  f£d  ”T0  is  to  be  searched  for  the  indicated  file 

(EXAMPL.MAC) .  If  the  file  is  not  found  after  four  files  have  been 

skipped,  or  if  an  end-of-tape  occurs  in  that  space,  the  search  is 

stopped,  and  the  tape  is  positioned  either  at  the  end-of-tape  (EOT)  or 

^  f^fth  ff1?*  If  the  name<3  file  is  found  within  the 
five  files,  the  tape  is  positioned  at  its  start.  If  the  EOT  is 
encountered  first,  an  error  is  generated. 

As  another  example: 

.LOOKUP  •APEA,*0,#PTR,#»5 

This  performs  a  rewind,  and  then  uses  a  file  count  of  five  in  the  same 
way  the  above  example  does. 
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H.2.4.2  Handler  Functions 

1.  LOOKUP 

If  the  filename  (or  the  first  word  of  the  filename)  is  null, 
the  operation  is  considered  to  be  a  non- file  structured 
LOOKUP.  This  operation  puts  the  handler  into  hardware  mode. 
A  rewind  is  automatically  done  in  this  case. 

If  the  filename  is  not  null,  the  handler  tries  to  find  the 
indicated  file.  LOOKUP  uses  the  optional  file  count  as 
illustrated  above.  Only  software  functions  are  allowed. 


2 .  DELETE 

DELETE  will  delete  a  file  of  the  indicated  name  from  the 
device.  DELETE  also  uses  the  file  count  argument,  and  can 
thus  do  a  delete  of  a  numbered  file  as  well  as  a  delete  by 
name.  When  a  file  is  deleted  from  MT  or  CT,  an  unused  space 
is  created  there.  However,  it  is  not  possible  to  reclaim 
that  space,  as  it  is  when  the  device  is  random  access.  The 
unused  spot  will  remain  until  the  volume  is  re-initialized 
and  rewritten. 


3.  ENTER 

ENTER  creates  a  new  file  of  the  indicated  name  on  the  device. 
ENTER  uses  the  optional  file  count,  and  can  thus  ENTER  a  file 
by  name  or  by  number.  If  ENTER  by  name  is  done,  the  handler 
deletes  any  files  of  the  same  name  it  finds  in  passing.  If 
ENTER  by  number  is  done,  the  indicated  number  of  files  is 
skipped,  and  the  tape  is  positioned  at  the  start  of  the  next 
file. 

NOTE 

Care  must  be  used  in  performing  numbered 
ENTERS,  as  it  is  possible  to  ENTER  a 
file  in  the  middle  of  existing  files  and 
thus  destroy  any  files  from  the  next 
file  to  the  end  of  the  tape. 

If  is  also  possible  to  create  more  than 
one  file  with  the  same  name,  since  ENTER 
will  only  delete  files  of  the  same  name 
it  sees  while  passing  down  the  tape.  If 
an  ENTER  is  done  with  a  count  greater 
than  0,  no  rewind  is  performed  before 
the  file  is  entered.  If  a  file  of  the 
same  name  is  present  at  an  earlier  spot 
on  the  tape,  the  handler  cannot  delete 
it.  A  non- file  structured  ENTER 
performs  the  same  function  as  a  non-file 
structured  LOOKUP  but  does  not  rewind 
the  tape.  Since  both  functions  allow 
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writing  to  the  tape  without  regard  to 
the  tape's  file  structure,  they  should 
be  used  with  care  on  a  file  structured 
tape. 


4.  CLOSE 

CLOSE  terminates  operations  to  a  file  on  magtape  or  cassette 
and  resets  the  handler  to  allow  more  LOOKUPS,  ENTERS,  or 
DELETES.  If  a  CLOSE  is  not  performed  to  an  ENTERed  file,  the 
end-of-tape  mark  will  be  missing  and  no  new  files  can  be 
created  on  that  volume.  In  this  case,  the  last  file  on  the 
tape  must  be  rewritten  and  CLOSEd  to  create  a  valid  volume. 


5.  READ/WRITE 

READ  and  WRITE  are  unique  in  that  they  can  be  done  either  in 
hardware  or  software  mode.  In  software  mode  (file  opened 
with  LOOKUP  or  ENTER) ,  records  are  written  in  a  fixed  size 
(256  words  for  magtape,  64  words  for  cassette).  The  word 
count  specified  in  the  operation  is  translated  to  the  correct 
number  of  records.  On  a  READ,  the  user  buffer  is  filled  with 
zeroes  if  the  word  count  exceeds  the  amount  of  data 
available. 

Following  is  a  discussion  of  how  the  various  parameters  for 
READ/WRITE  are  used  for  magtape  and  cassette. 

a.  Block  Number 

For  READ  operations  to  magtape,  the  block  number  is 
used  for  random  access  (i.e.,  blocks  need  not  be 
read  sequentially  from  magtape).  WRITE  operations, 
however,  disregard  the  block  number  and  merely  write 
the  next  sequential  block.  Block  0  on  either  READ 
or  WRITE  causes  the  device  to  rewind  to  the  start  of 
the  file.  A  subsequent  WRITE  will  destroy  all 
previous  output  to  that  file. 

For  cassette,  only  sequential  operations  are 
performed.  If  the  block  number  is  0,  the  cassette 
is  rewound  to  the  start  of  the  file.  Any  other 
block  number  is  disregarded. 


b.  Word  Count 

On  a  magtape  READ,  if  the  word  count  is  0,  the  block 
number  is  ignored  and  the  next  sequential  record  is 
read,  no  matter  how  big  it  is. 

NOTE 

Care  must  be  taken  when  performing  a 
magtape  READ,  because  the  READ  will  be 
done  even  if  the  record  to  be  read  is 
larger  than  the  buffer  allocated. 
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On  a  magtape  WRITE,  if  the  word  count  is  0,  one 
256-word  block  is  written. 

If  the  word  count  for  cassette  is  0,  the  following 
conditions  are  possible: 

If  the  block  number  is  non-zero,  the  operation  is 
actually  a  file-name  seek.  The  block  number  is 
interpreted  as  the  file  count  argument,  as  discussed 
in  the  above  example  of  LOOKUP.  The  buffer  address 
should  point  to  the  RAD50  of  the  device  and  file  to 
be  located.  This  feature  essentially  allows  an 
asynchronous  LOOKUP  to  be  performed.  The  standard 
LOOKUP  request  does  not  return  control  to  the  user 
program  if  the  tape  has  been  positioned  properly, 
whereas  this  asynchronous  version  will  return 
control  and  interrupt  when  the  file  is  positioned. 


The  user  may  then  do  a  synchronous,  positively 
numbered  LOOKUP  to  the  file  just  positioned,  thus 
avoiding  a  long  synchronous  search  of  the  tape. 

If  the  block  number  is  0,  a  CRC  (cyclical  redundancy 
check)  error  occurs. 

Following  is  a  description  of  the  allowed  hardware  mode  functions  for 
the  handlers,  as  well  as  examples  of  how  to  call  them.  In  general, 
special  functions  are  called  by  using  the  .SPFUN  request;  examples  of 
usage  follow  each  function.  The  special  functions  require  a  channel 
number  as  an  argument.  The  channel  must  initially  be  opened  with  a 
non-file  structured  LOOKUP  which  places  the  handler  in  hardware  mode. 


The  general  form  of  the  .SPFUN  request  is: 


.SPFUN  . are  a , . chan , . code , .buff, .went, .blk,. ertn 
where : 

.code  is  the  function  code  to  be  performed. 
The  request  format  is: 

R0  =►  .area: 


32 


.chan 


.blk 


.buff 


.went 


.code  377 


.ertn 


1.  Magtape  Special  Functions 


a.  Rewind  (Code  =  373)  -  Rewinds  the  tape  to  the  load  point. 
This  puts  the  unit  into  hardware  mode  (as  does  a  non-file 
structured  LOOKUP)  where  any  of  the  other  functions  may 
be  done. 

Sample  Macro  Call: 


.SPFUN  #AREA,#0,*J73 
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The  above  performs  a  synchronous  rewind  on  channel  0 
(i.e.,  control  will  not  return  before  the  tape  is 
positioned).  An  asynchronous  rewind  could  be  done  with: 

, SPFUN  «AREA,#0,#373,,,,#CRTN  jREWIND  Mf,  CHANNEL  0 

where  CRTN  is  a  completion  routine  to  be  entered  when  the 
operation  is  finished.  The  other  arguments  are  not 
required  for  this  call. 


b.  Write  End-of-File  (Code  =  377)  -  This  request  writes  am 
end-of-file  mark,  thus  terminating  a  file. 

Sample  Macro  Call: 

.SPFUN  #AREA,#0,#377  »THIS  IS  THE  SYNCHRONOUS  FORM 

The  asynchronous  form  is : 

.SPFUN  #AREA,*0, #377, , , ,#CRTN  » WRITE  EOF  ON 

>MT,  CHANNEL  0 


c.  Forward  Space  (Code  «*  376)  -  This  function  spaces  forward 
the  specified  number  of  records  amd  then  stops.  If  the 
EOT  or  EOF  is  discovered  before  the  count  is  exhausted, 
the  tape  stops  there.  Note  that  the  number  of  records  to 
space  forward  is  contained  in  the  word  count  argument, 
amd  the  number  passed  should  be  the  positive  value  of  the 
desired  number. 

Sample  Macro  Call: 

.SPFUN  #AREA,#0,#376, ,#2  iSPACE  FORWARD  2 

^RECORDS,  CHANNEL  0 

This  spaces  forward  two  records. 


d.  Back  Space  (Code  =  375)  -  This  is  similar  to  Forward 

Space  except  the  tape  is  backed  up  by  the  indicated 
number  of  blocks.  Again,  the  word  count  must  be  the 
positive  value  of  the  number  to  back  up. 

Sample  Macro  Call: 

.SPFUN  #AREA,#0,#375,»#2 

This  backs  the  tape  up  by  two  records. 


e.  Write  With  Extended  Gap  (Code  =  374)  -  This  request  is 

the  same  as  any  of  the  WRITE  requests,  except  that  a 
longer  file  gap  is  written  between  records.  This  can  be 
used  to  get  past  bad  spots  on  the  tape. 
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.SPFUN  #AREA,«0,#374,#BUFF,#i00.,#0 

This  performs  a  synchronous  write,  while: 

.SPFUN  *AREA,#8»#374,*BUFF,#100. ,*l,#CRTN 

is  asynchronous  and  goes  to  CRTN  when  the  operation  is 
complete. 


f.  Offline  (Code  «  372)  -  This  request  sets  the  drive  to  an 
off-line  state.  The  unit  can  only  be  set  on-line  by 
manual  control. 

Sample  Macro  Call: 

.SPFUN  #AREA, #0,4372 

Since  this  in  an  ins tarn taneous  function,  no  asynchronous 
forms  are  required. 


2.  Cassette  Special  Functions 

With  exceptions  noted,  these  requests  are  identical  to  those 

involving  magtape. 

a.  Rewind  (Code  ■  373)  -  This  request  is  identical  to  the 
rewind  request  for  magtape,  except  that  unless  a 
completion  routine  is  specified,  control  does  not  return 
to  the  user  until  the  rewind  completes. 

b.  Last  File  (Code  =  377) -  This  request  rewinds  the  cassette 
and  positions  it  immediately  before  the  sentinel  file 
(logical  end-of-tape) .  The  macro  call  is  the  same  as  for 
magtape  code  377. 

c.  Last  Block  (Code  =  376)-  This  request  rewinds  one  record. 
See  the  magtape  code  376  for  a  sample  macro  call. 

d.  Next  File  (Code  =  375)-  This  request  spaces  the  cassette 
forward  to  the  next  file. 

e.  Next  Block  (Code  =  374)-  This  request  spaces  the  cassette 
forward  by  one  record. 
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f.  Write  File  Gap  (code  =  372)  -  This  request  terminates  a 
file  written  by  the  user  program  when  in  hardware  mode. 

Sample  Macro  Call: 

• SPFUN  *AREA,#0,#372 

This  writes  a  file  gap  synchronously,  while: 

.SPFUN  #AREA,#0,#372»»»»#1 
or 

.SPFUN  #AREA,*0,#372»»»H<CPTN 
performs  asynchronous  write  file  gap  operations. 
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H. 4  DEC  026/DEC  029  CARD  CODE  CONVERSION  TABLE 

Card  codes  in  the  following  table  are  broken  down  by  zone  punch. 

Except  where  noted,  all  codes  apply  to  both  DEC  026  and  DEC  029  punched 
cards. 


Table  H-l 

Card  Code  Conversions 


Zone 

Digit 

Octal 

Character 

Name 

none 

none 

040 

SPACE 

1 

061 

1 

digit  1 

2 

062 

2 

digit  2 

3 

063 

3 

digit  3 

4 

064 

4 

digit  4 

5 

065 

5 

digit  5 

6 

066 

6 

digit  6 

12 

7 

067 

7 

digit  7 

(DEC 

029) 

none 

046 

& 

ampersand 

(DEC 

026) 

053 

+ 

plus  sign 

1 

101 

A 

upper  case  A 

2 

102 

B 

upper  case  B 

3 

103 

C 

upper  case  C 

4 

104 

D 

upper  case  D 

5 

105 

E 

upper  case  E 

6 

106 

F 

upper  case  F 

11 

7 

107 

G 

upper  case  G 

none 

055 

_ 

minus  sign 

1 

112 

J 

upper  case  J 

2 

113 

K 

upper  case  K 

3 

114 

L 

upper  case  L 

4 

115 

M 

upper  case  M 

5 

116 

N 

upper  case  N 

6 

117 

0 

upper  case  0 

0 

7 

107 

P 

upper  case  P 

none 

060 

0 

digit  0 

1 

057 

/ 

slash 

2 

123 

S 

upper  case  S 

3 

124 

T 

upper  case  T 

4 

125 

U 

upper  case  U 

5 

126 

V 

upper  case  V 

6 

127 

W 

upper  case  W 

8 

7 

130 

X 

upper  case  X 

none 

70 

8 

digit  8 

(DEC 

1 

140 

accent  grave 

029) 

2 

072 

: 

colon 

(DEC 

026) 

137 

backarrow 

(DEC 

029) 

(underscore  J 

3 

043 

# 

number  sign 

(continued  on  next  page) 


H-23 


F/B  Programming  and  Device  Handlers 

Table  H-l  (Cont.) 
Card  Code  Conversions 


Zone 

Digit 

Octal 

Character 

Name 

(DEC  026) 

075 

= 

equal  sign 

4 

100 

@ 

commercial  "at" 

(DEC  029) 

5 

047 

» 

single  quote 

(DEC  026) 

136 

uparrow 

(circumflex) 

(DEC  029) 

6 

075 

= 

equal  sign 

(DEC  026) 

047 

? 

single  quote 

(DEC  029) 

7 

042 

it 

double  quote 

(DEC  026) 

n 

134 

\ 

backslash 

none 

071 

9 

digit  9 

2 

02  6 

Ctrl  -  V 

SYN 

7 

004 

Ctrl  -  D 

EOT 

12-11 

none 

174 

1 

vertical  bar 

1 

152 

j 

lower-case  J 

2 

153 

k 

lower-case  K 

3 

154 

1 

lower-case  L 

4 

155 

m 

lower-case  M 

5 

156 

n 

lower-case  N 

6 

157 

0 

lower-case  0 

7 

160 

P 

lower-case  P 

12-0 

none 

173 

{ 

open  brace 

1 

141 

a 

lower-case  A 

2 

142 

b 

lower-case  B 

3 

143 

c 

lower-case  C 

4 

144 

d 

lower-case  D 

5 

145 

e 

lower-case  E 

6 

146 

f 

lower-case  F 

7 

147 

g 

lower-case  G 

12-8 

none 

110 

H 

upper-case  H. 

(DEC  029) 

2 

133 

C 

open  square  bracket 

(DEC  026) 

077 

? 

question  mark 

3 

056 

• 

period 

(DEC  029) 

4 

074 

< 

open  angle  bracket 

(DEC  026) 

051 

) 

close  parenthesis 

(DEC  029) 

5 

050 

( 

open  parenthesis 

(DEC  026) 

135 

] 

close  square  bracket 

(DEC  029) 

6 

053 

+ 

plus  sign 

(DEC  026) 

074 

< 

open  angle  bracket 

7 

041 

! 

exclamation  mark 

12-9 

none 

111 

I 

upper-case  I 

1 

001 

Ctrl  -  A 

SOH 

2 

002 

Ctrl  -  B 

STX 

3 

003 

Ctrl  -  C 

ETX 

5 

011 

Ctrl  -  I 

HT 

7 

177 

DEL 

(continued  on  next  page) 
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Table  H-l  (Cont.) 
Card  Code  Conversions 


Zone 

Digit 

Octal 

Character 

Name 

11-0 

none 

175 

i 

close  brace 

1 

176 

tilde 

2 

163 

s 

lower-case  S 

3 

164 

t 

lower-case  T 

4 

165 

u 

lower-case  U 

5 

166 

V 

lower-case  V 

6 

167 

w 

lower-case  W 

7 

170 

X 

lower-case  X 

11-8 

none 

121 

Q 

upper-case  Q 

(DEC  029) 

2 

135 

] 

close  square  bracket 

(DEC  026) 

072 

: 

colon 

3 

044 

$ 

currency  symbol 

4 

052 

# 

asterisk 

(DEC  029) 

5 

051 

) 

close  parenthesis 

(DEC  026) 

133 

[ 

open  square  bracket 

(DEC  029) 

6 

073 

y 

semi-colon 

(DEC  026) 

076 

> 

close  angle  bracket 

(DEC  029) 

7 

136 

t 

uparrow 

(circumflex) 

(DEC  026) 

046 

& 

ampersand 

11-9 

none 

122 

R 

upper-case  R 

1 

021 

Ctrl  -  Q 

DC1 

2 

022 

Ctrl  -  R 

DC2 

3 

023 

Ctrl  -  S 

DC3 

6 

010 

Ctrl  -  H 

BS 

0-8 

null 

131 

Y 

upper-case  Y 

(DEC  029) 

2 

134 

\ 

backslash 

(DEC  026) 

073 

y 

semi-colon 

3 

054 

y 

comma 

(DEC  029) 

4 

045 

% 

percent  sign 

(DEC  026) 

050 

( 

open  parenthesis 

(DEC  029) 

5 

137 

«- 

backarrow 

(underscore) 

(DEC  026) 

042 

tf 

double  quote 

(DEC  029) 

6 

076 

> 

close  angle  bracket 

(DEC  026) 

043 

# 

number  sign 

(DEC  029) 

7 

077 

? 

question  mark 

(DEC  026) 

045 

% 

percent  sign 

0-9 

.  null 

132 

z 

upper-case  Z 

5 

012 

Ctrl  -  J 

LF 

6 

027 

Ctrl  -  W 

ETB 

7 

033 

ESC 

9-8 

4 

024 

Ctrl  -  T 

DC4 

5 

025 

Ctrl  -  U 

NAK 

7 

032 

Ctrl  -  Z 

SUB 

(continued  on  next  page) 
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Table  H-l  (Cont.) 
Card  Code  Conversions 


Zone 

Digit 

Octal 

Character 

Name 

12-9-8 

3 

013 

Ctrl  -  K 

VT 

4 

014 

Ctrl  -  L 

FF 

5 

015 

Ctrl  -  M 

CR 

6 

016 

Ctrl  -  N 

SO 

7 

017 

Ctrl  -  0 

SI 

11-9-8 

none 

030 

Ctrl  -  X 

CAN 

1 

031 

Ctrl  -  Y 

EM 

4 

034 

Ctrl  -  \ 

FS 

5 

035 

Ctrl  -  ] 

GS 

6 

036 

Ctrl  -  + 

RS 

7 

037 

Ctrl  - 

US 

0-9-8 

5 

005 

Ctrl  -  E 

ENQ 

6 

006 

Ctrl  -  F 

ACK 

7 

007 

Ctrl  -  G 

BEL 

12-0-8 

none 

150 

h 

lower-case  H 

12-0-9 

none 

151 

i 

lower-case  I 

12-11-8 

none 

161 

q 

lower-case  Q 

12-11-9 

none 

162 

r 

lower-case  R 

11-0-8 

none 

171 

y 

lower-case  Y 

11-0-9 

none 

172 

z 

lower-case  Z 

12-11-9-8 

1 

020 

Ctrl  -  P 

DLE 

12-0-9-8 

1 

000 

NUL 

H-26 


APPENDIX  I 


DUMP 


RT-11  DUMP  is  a  program  which  outputs  to  the  console  or  lineprinter 
all  or  any  part  of  a  file  in  octal  words,  octal  bytes,  ASCII 
characters  and/or  RAD50  characters.  DUMP  is  particularly  useful  for 
examining  data  such  as  directories  or  files. 


1.1  CALLING  AND  USING  DUMP 

DUMP  is  called  using  the  monitor  command: 

R  DUMP 

in  response  to  the  dot  printed  by  the  Keyboard  Monitor.  The  name  of 
the  file  which  is  to  be  output  is  entered  as  follows  in  response  to 
the  asterisk  printed  by  the  Command  String  Interpreter: 

dev : outpu t=de v : input /s 


where : 

dev:  represents  any  valid  device  specification  (line  printer 

is  default  for  output  if  no  output  file  is  designated) . 

output  represents  the  filename  and  extension  assigned  to  the 

output  file.  The  default  extension  for  file-structured 
output  is  . DMP . 

input  represents  the  input  source  filename  and  extension. 

/s  represents  one  or  more  of  the  switches  listed  in  Table 

1-1. 

Type  CTRL  C  to  halt  DUMP  at  any  time  and  return  control  to  the 

monitor.  To  restart  DUMP  type  R  DUMP  or  the  REENTER  command  in 

response  to  the  monitor's  dot. 


1-1 


DUMP 


1.1.1  DUMP  Switches 

The  following  switches  can  appear  in  the  command  string  for  DUMP: 


Table  1-1 
DUMP  Switches 


Switch 

Meaning 

/B 

Output  octal  bytes 

/E:n 

End  output  at  block  number  n 

/G 

Ignore  input  errors 

/N 

Suppress  ASCII  output 

/Osn 

Output  only  block  number  n  (same  as  /Esn, 
/S:n) 

/S:n 

Start  output  with  block  number  n 

/w 

Output  octal  words 

/X 

Output  RAD50  characters 

If  neither  /W  nor  /B  is  given,  /W  is  assumed.  ASCII  characters  are 
always  dumped  unless  /N  is  given.  The  number  n  is  an  octal  block 
number. 

If  an  input  filename  is  given,  block  numbers  are  relative  to  the 
beginning  of  the  file  to  which  the  block  belongs.  If  not,  block 
numbers  are  absolute  block  numbers  on  the  device  (i.e.,  the  physical 
block  numbers  on  the  corresponding  device) . 


1.1.2  Examples 

The  following  are  two  examples  of  DUMP.  /B  is  used  in  the  first 
example  to  output  octal  bytes  of  the  file  SQRT.FTN  into  a  file  called 
DIF.DMP  on  device  DTI. 

R  DUMP 

*DT1 : DIF  =SQRT.  FTN/B 


If  DIF.DMP  is 
as  follows: 

BLOCK  NUMBER 

then 

0000 

listed 

t 

on  the  line 

printer 

(using  PIP)  , 

it 

appears 

000/ 

001 

000 

036 

000 

001 

000 

011 

261 

214 

072 

150 

000 

000 

000 

001 

257 

• 

• 

• 

• 

0 

t 

• 

1 

» 

1 

N 

• 

* 

■ 

• 

/ 

020/ 

224 

017 

110 

001 

000 

000 

262 

252 

304 

037 

110 

004 

210 

000 

374 

252 

• 

• 

M 

• 

t 

• 

2 

• 

D 

• 

H 

• 

* 

• 

6 

« 

040/ 

016 

024 

110 

004 

006 

000 

033 

254 

217 

163 

110 

004 

000 

000 

012 

001 

• 

• 

H 

t 

• 

• 

• 

# 

• 

9 

H 

• 

• 

« 

• 

• 

060/ 

000 

036 

000 

001 

000 

054 

253 

100 

070 

100 

004 

000 

000 

123 

263 

024 

• 

• 

• 

• 

• 

♦ 

» 

8 

0 

• 

• 

• 

S 

3 

• 

100/ 

239 

150 

001 

000 

000 

000 

000 

000 

000 

000 

003 

000 

000 

032 

001 

000 

DUMP 


120/ 

016 

000 

204 

000 

00; 

000 

000 

• 

• 

• 

• 

• 

9 

• 

140/ 

000 

003 

200 

000 

000 

067 

011 

• 

• 

i 

t 

9 

7 

9 

100/ 

004 

000 

004 

006 

054 

253 

100 

• 

• 

• 

• 

f 

♦ 

0 

200/ 

000 

000 

000 

000 

000 

000 

000 

• 

i 

• 

t 

• 

• 

• 

220/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

■ 

• 

• 

• 

9 

240/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

• 

• 

• 

9 

9 

200/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

• 

• 

• 

9 

9 

300/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

■ 

* 

• 

t 

• 

320/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

• 

• 

• 

• 

9 

340/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

• 

• 

• 

§ 

• 

300/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

* 

* 

• 

• 

• 

400/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

* 

• 

• 

• 

• 

420/ 

000 

000 

000 

000 

000 

000 

000 

a 

• 

• 

• 

• 

• 

• 

440/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

« 

• 

• 

• 

a 

460/ 

000 

000 

000 

000 

000 

000 

000 

a 

• 

• 

• 

• 

• 

9 

900/ 

000 

000 

000 

000 

000 

000 

000 

a 

* 

• 

• 

• 

a 

920/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

i 

« 

• 

• 

a 

940/ 

000 

000 

000 

000 

000 

000 

000 

a 

• 

• 

* 

9 

9 

a 

960/ 

000 

000 

000 

000 

000 

000 

000 

a 

• 

• 

* 

9 

• 

9 

600/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

i 

• 

9 

9 

9 

020/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

• 

• 

9 

• 

• 

640/ 

000 

000 

000 

000 

000 

000 

000 

■ 

• 

• 

• 

9 

• 

9 

660/ 

000 

000 

000 

000 

000 

000 

000 

• 

$ 

• 

t 

9 

9 

9 

700/ 

000 

000 

000 

000 

000 

000 

000 

• 

• 

« 

• 

9 

9 

9 

'V 

9 

M 

tv 

000 

000 

000 

000 

000 

000 

000 

a 

• 

t 

• 

• 

• 

a 

740/ 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

346 

061 

000 

016 

a 

a 

a 

• 

F 

l 

a 

a 

371 

000 

000 

167 

001 

000 

014 

000 

Y 

a 

a 

4 

• 

i 

• 

• 

226 

000 

000 

000 

000 

000 

000 

000 

9 

a 

a 

9 

9 

• 

a 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

• 

a 

• 

• 

• 

000 

000 

000 

000 

000 

000 

000 

000 

9 

• 

• 

9 

a 

• 

• 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

• 

• 

a 

a 

• 

* 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

a 

• 

• 

• 

• 

000 

000 

000 

000 

000 

000 

000 

000 

9 

a 

a 

a 

a 

• 

t 

9 

000 

000 

000 

000 

000 

000 

000 

000 

9 

• 

a 

a 

a 

• 

• 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

a 

a 

• 

• 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

a 

a 

• 

t 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

a 

a 

• 

« 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

a 

a 

■ 

• 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

• 

a 

• 

a 

• 

» 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

a 

a 

• 

* 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

• 

a 

• 

• 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

a 

a 

t 

* 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

9 

9 

« 

• 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

• 

a 

• 

• 

a 

000 

000 

000 

000 

000 

000 

000 

000 

a 

a 

a 

• 

• 

• 

• 

9 

000 

000 

000 

000 

000 

000 

000 

000 

• 

a 

a 

• 

9 

• 

• 

9 

000 

090 

000 

000 

000 

000 

000 

000 

a 

a 

a 

9 

• 

• 

• 

§ 

000 

000 

000 

000 

000 

000 

000 

000 

a 

• 

a 

a 

a 

• 

• 

9 

000 

000 

000 

000 

000 

000 

000 

000 

• 

a 

a 

• 

• 

* 

« 

9 

000 

000 

000 

000 

000 

000 

000 

000 

9 

a 

a 

9 

a 

• 

• 

• 

000 

000 

000 

000 

000 

000 

000 

000 

000 

070 

» 

070 

0 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 

000 


780/  000  000  000  000  000  000  000  000  000  000  000  000  000  000  000 


DUMP 


The  second  example  illustrates  the  use  of  /X  to  output  RAD50  and 
octal  values  for  locations  in  the  file.  The  numbers  in  the  left 
column  represent  the  byte  displacement.  ASCII  characters  are  printed 
in  the  far  right  hand  column  (dot  represents  a  non-printing 
character) : 

R  DUMP 

*RK1:L1NK0  FB/X 


000/ 

027k)U 

044524 

046124 

**4505 

052122 

044514 

045516 

051040 

*.. title. RTLInk  r* 

gny 

R/L 

LHT 

ASM 

MSZ 

R/D 

LA8 

MEX 

020/ 

047917 

020124 

047503 

042504 

020040 

054040 

091460 

030455 

*00T  CODE  X03-1* 

lip 

efo 

LSK 

KCt 

EEX 

NO 

HGX 

G4/ 

040/ 

000406 

099412 

091040 

026524 

030461 

046040 

047111 

042513 

*6,,;  RT-ll  LINKE* 

BOV 

1Q4 

MEX 

6  JO 

G43 

LGH 

LUA 

KCS 

000/ 

006922 

039412 

042040 

041505 

030455 

026461 

051117 

046114 

*«.,»  DEC-U-URLL* 

BEJ 

IQ4 

J6 

J0U 

G4/ 

Oil 

MFl 

UML 

100/ 

026901 

026902 

040914 

005015 

020373 

040515 

020131 

032461 

•A.B-LA..I  MAY  15* 

Cl  V 

Cl! 

JQ6 

AX* 

EFK 

JQ7 

EGA 

HTO 

120/ 

020094 

034461 

092067 

005015 

020073 

050105 

020057 

047105 

*»  1974..;  EP/  EN* 

EE6 

IF  A 

HNG 

A  X  M 

EFK 

13/ 

EE9 

LT7 

140/ 

040910 

041916 

042105 

041040 

020131 

043512 

005015 

005015 

♦hanceo  sy  jg....* 

JQ2 

J  0  0 

J67 

J4M 

EGA 

RPJ 

AXM 

AXM 

160/ 

006479 

039412 

041440 

050117 

091131 

043511 

052110 

024040 

*;.,;  copyright  c* 

BOS 

104 

J/X 

139 

MGA 

RPI 

M3P 

FP2 

200/ 

024903 

024040 

034461 

052067 

006451 

035412 

000440 

035412 

*C)  (1974), .1  ..;* 

FXC 

FP2 

ifa 

HNG 

BOX 

104 

BO 

104 

220/ 

042040 

043511 

092111 

040101 

042440 

092521 

050111 

042515 

*  DIGITAL  EQUIPME* 

J6 

RPI 

MSB 

LHA 

KBP 

MZA 

L33 

KCU 

240/ 

092110 

041440 

051117 

047520 

040922 

044524 

047117 

005015 

•NT  CORPORATION..* 

MSV 

in 

MFl 

USX 

JRB 

R/L 

LUG 

AXM 

260/ 

020079 

040515 

047131 

051101 

026104 

046440 

091901 

040523 

•;  MAYNARD.  MASSA* 

CM 

JQ7 

LUU 

HFQ 

GCL 

LMX 

ML3 

JRC 

900/ 

044109 

091529 

092105 

051524 

090040 

033461 

032065 

005015 

•ChUSETTS  01754..* 

KV3 

mmm 

M3M 

MML 

G, 

H3I 

HNE 

AXM 

920/ 

006479 

035412 

052040 

042510 

044440 

043116 

051117 

040515 

*;,,;  THE  INFORMA* 

60S 

104 

MRP 

KCP 

R  • 

RIO 

MFl 

JQ7 

940/ 

044924 

047117 

044440 

020116 

044124 

051511 

042040 

041517 

*TI0n  IN  THIS  DOC* 

K/L 

LUG 

Ft 

EF0 

RV6 

MM  A 

J6 

J01 

960/ 

046929 

047109 

020124 

051511 

091440 

041125 

042512 

052103 

•ument  is  subject* 

1*7 

LT7 

EF6 

MM  A 

ML 

JXU 

KCR 

MSK 

400/ 

092040 

006517 

033412 

041440 

040910 

043516 

020105 

044527 

*  TO..;  CHANGE  HI* 

MRP 

BCG 

104 

J/X 

JQ2 

KPN 

EFU 

K/Q 

420/ 

044124 

052517 

020124 

047516 

044924 

042503 

040440 

042116 

•THOUT  NOTICE  ANO* 

KV6 

MY0 

CP6 

UJV 

R/L 

KCK 

JP2 

J7F 

440/ 

091440 

047910 

046125 

020104 

047916 

020124 

042502 

041440 

*  SHOULD  NOT  BE  C* 

ml 

LSP 

LMU 

6FT 

LSV 

EF6 

KCJ 

J/* 

460/ 

047117 

052129 

052522 

042105 

005015 

020P73 

051901 

040440 

•onstrueo..;  as  a* 

cue 

MSS 

MZB 

J67 

AXM 

EFK 

ML3 

JP2 

500/ 

041440 

046517 

044515 

046524 

047109 

020124 

054902 

042040 

*  COMMITMENT  by  0* 

J/X 

LN1 

K/E 

LN6 

LT7 

EF6 

NK  J 

J6 

520/ 

049911 

040511 

020124 

050505 

044525 

046520 

047105 

020124 

•IGIAT  EQUIPMENT  * 

API 

JQ9 

EF6 

H  t 

K/M 

LN2 

LT7 

EF6 

540/ 

047909 

090122 

051117 

052101 

047511 

027116 

005015 

020073 

•corporation...;  * 

l»K 

L40 

MF  1 

MSI 

ISO 

GPN 

AXM 

EFK 

500/ 

042904 

020109 

051501 

052523 

042915 

020123 

047516 

051040 

•DEC  ASSUMES  NO  R* 

KCL 

EF3 

ML3 

MZC 

KCU 

EF5 

LSV 

MEX 

600/ 

091909 

047520 

051516 

041111 

046111 

052111 

020131 

047506 

•EsPONSIBILITY  fo* 

ML7 

c$x 

MMP 

JXI 

LMI 

MSB 

EGA 

LSN 

620/ 

020122 

047101 

020131 

051105 

047522 

091522 

052040 

040510 

*r  any  errors  tha* 

6P4 

LT3 

EGA 

MFU 

LSZ 

MMJ 

MRP 

J02 

640/ 

006924 

099412 

046440 

054501 

040440 

050120 

040505 

020122 

*T, . ;  MAY  APPEAR  * 

BEl 

IQ4 

LMX 

NK  I 

JP2 

L4 

JO/ 

EF4 

1-4 
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960/  047111  053040  044510  020123  047504  050503  042515  053116  *lN  THIS  OQCUHENT* 
LUA  MRP  K/  EF5  USC  MYS  KCU  MSV 

700/  005456  035412  005015  020073  044124  051511  051440  043117  *.,.|,.j  THIS  SOP* 
BON  IQ4  AXM  EFK  KV6  MMA  MU  KI9 

720/  053524  051101  020105  051511  043040  051125  044516  044123  *T«ARE  IS  FURNISH* 
M86  NFS  fcFU  MMA  KM2  MF7  K/F  KVS 

740/  042105  052040  020H7  052520  041522  040510  042923  020122  *E0  TO  PURCHASER  * 
J97  MRP  EF 1  MI  J04  JQ2  KCS  EF4 


760/  047125  042504  020122  006501  035412  046040  041511  047105  *UnOER  A UlCEN* 

UUM  KCU  tF4  B03  104  UGH  J0Y  UT7 


1.2  DUMP  ERROR  MESSAGES 


The  following  errors  may  occur  when  using  DUMP: 
Message  Meaning 


?IN  ERR? 


POUT  ERR? 


A  hardware  error  occurred  while 
reading  the  input  file  and  /G  was 
not  specified  in  the  command  line. 

A  hardware  error  occurred  while 
writing  an  output  file,  or  the 
output  device  was  full. 


?LP  NOT  FND? 


A  line  printer  handler  is 
available  on  the  system. 


not 
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FILEX 


J.l  FILEX  OVERVIEW 

FILEX  is  a  general  file  transfer  program  used  to  convert  files  among 
file- formatted  devices  for  various  operating  systems.  Transfers  may 
be  initiated  between  any  file-structured  RT-11  device  and  PDP-11 
DOS/BATCH  DECtape  (as  input  or  output) ,  DOS/BATCH  disk  (as  input  only) , 
RSTS-11  DECtape  (as  input  or  output) ,  and  DECsystem-10  DECtape  (as 
input  only) .  Files  are  transferred  as  16-bit  binary  data.  No 
processing  is  done  on  the  data  itself  except  that  which  is  necessary 
to  convert  between  various  data  representations. 

"Wild-card"  names  (the  *.*  construction  explained  in  Chapter  4)  are 
permitted. 


J.1.1  File  Formats 

FILEX  can  transfer  files  created  by  three  different  operating 
systems— RT-11,  DECsystem-10,  and  DOS /BATCH  (PDP-11  Disk  Operating 
System/BATCH) .  Data  formats  that  may  be  used  in  a  transfer  are  ASCII, 
image,  and  packed  image.  Because  the  file  structure  for  each  system 
varies  somewhat,  switches  are  needed  in  the  command  line  to  indicate 
the  file  structures  used  and  the  data  format  conversion  (if  any)  to  be 
performed.  These  switches  are  defined  in  Section  J.2.1.  Devices  are 
assumed  to  be  in  RT-11  file  structure  unless  either  a  /S  or  /T  switch 
(for  DOS/BATCH  and  RSTS-11  or  DECsystera-10  respectively)  is  indicated. 
If  both  input  and  output  devices  are  RT-11  format  (or  are  not 
file-structured),  FILEX  will  operate  like  PIP. 


J.2  CALLING  AND  USING  FILEX 

FILEX  is  called  from  the  RT-11  system  device  by  typing: 

R  FILEX 

in  response  to  the  dot  printed  by  the  Keyboard  Monitor.  An  asterisk 
is  printed  when  FILEX  is  loaded  and  ready  to  accept  command  string 
input. 


J-l 


FILEX 


Type  CTRL  C  to  halt  FILEX  at  any  time  and  return  control  to  the 
monitor.  To  restart  FILEX,  type  R  FILEX  or  the  REENTER  command  in 
response  to  the  monitor's  dot. 


J.2.1  FILEX  Switch  Options 

Table  J-l  lists  the  switch  options  which  are  used  for  various  FILEX 
operations.  /S  and  /T  must  appear  following  the  device  and  filename 
to  which  they  apply;  other  switches  may  appear  anywhere  in  the 
command  line.  These  switches  are  explained  in  more  detail  following 
the  table. 


Table  J-l 

FILEX  Switch  Options 


Switch  Meaning 


/A  Indicates  a  character-by-character  ASCII  transfer  in 

which  rubouts  and  nulls  are  deleted;  when  /T  is  also 
used,  each  PDP-10  word  is  assumed  to  contain  five  7-bit 
ASCII  bytes.  (The  transfer  terminates  upon  reaching  a 
tZ  for  compatibility  with  RSTS-11;  the  tZ  is  not 
transferred. ) 


/D 

/F 

/I 


/L 

/P 


/S 


Deletes  the  named  file  from  the  device;  valid  only  for 
DOS /BATCH  and  RSTS-11  DECtape. 

Causes  a  "fast"  listing  of  the  device  directory  by 
listing  filenames  only. 

Performs  an  image  mode  transfer;  if  the  input  is 
either  DOS /BATCH,  RSTS-11  or  RT-11,  this  is  a 
word-for-word  transfer;  if  the  input  is  from 
DECsystem-10 ,  /I  indicates  that  the  file  resembles  a 
file  created  on  DECsystem-10  by  MACY11,  MACX11,  or 
LNKXll  with  the  /I  switch:  in  this  case  each 
DECsystem-10  36-bit  word  contains  one  PDP-11  8-bit  byte 
in  its  low-order  bits. 

Causes  a  complete  listing  of  the  device  directory, 
including  filenames,  block  lengths,  and  creation  dates, 
to  appear  on  the  console  terminal. 

Performs  a  packed  image  transfer;  if  the  input  is 
either  DOS/BATCH,  RSTS-11  or  RT-11,  this  is  a 
word-for-word  transfer;  if  the  input  is  from 
DECsystem-10,  /P  indicates  that  the  file  resembles  a 
file  created  on  DECsystem-10  by  MACY11,  MACX11,  or 
LNKXll  with  the  /P  switch,  in  which  case  each 
DECsystem-10  36-bit  word  contains  four  PDP-11  8-bit 
bytes  aligned  on  bits  0,  8,  18,  and  26.  This  mode  is 
assumed  if  no  mode  switch  (/A,  /I)  is  indicated  in  a 
command  line. 

Indicates  the  device  is  a  DOS/BATCH  (or  RSTS-11) 
file-structured  device;  the  switch  must  appear  on  the 
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Table  J-l  (Cont) 
FILEX  Switch  Options 


Switch 

Meaning 

same  side  of  the  command  line  as  the  device  to  which  it 
applies . 

NOTE 

Neglecting  to  include  the  /S  switch  in  a 
command  line  involving  DOS/BATCH  (or 

RSTS-11)  causes  unpredictable  results. 

/T 

Indicates  the  device  is  a  DECsystem-10  file-structured 
device;  the  switch  must  appear  on  the  same  side  of  the 
command  line  as  the  device  to  which  it  applies. 

A 

Types  out  version  number  of  FILEX. 

/z 

Zeroes  the  directory  of  the  specified  device  in  the 
proper  format  (valid  only  for  DOS/BATCH  and  RSTS-11 
DECtape) . 

J.2.2  Transferring  Files  Between  RT-11  and  DOS /BATCH  (or  RSTS-11) 

File  transfers  may  be  initiated  between  file-structured  devices  used 
by  RT— 11  and  the  PDP-11  DOS/BATCH  system.  DECtape  used  under  the 
RSTS-11  system  is  also  legal  as  both  input  and  output,  since  its 
format  is  identical  to  DOS/BATCH  DECtape;  see  PDP-11  RESOURCE  SHARING 
TIME-SHARING  SYSTEM  USER'S  GUIDE,  DEC-ll-ORSUA-A-D.  Input  from 
DOS /BATCH  may  be  either  disk  or  DECtape;  both  linked  and  contiguous 
files  are  supported  as  input;  the  RT-11  device  DK:  is  assumed  if  no 
device  is  indicated.  If  the  input  device  is  a  DOS/BATCH  disk,  the 
user  should  specify  a  DOS/BATCH  user  identification  code  (called  a 
UIC — refer  to  the  PDP-11  DISK  OPERATING  SYSTEM  MONITOR  PROGRAMMER'S 
HANDBOOK,  DEC-ll-OMONA-A-D) ;  this  UIC  then  becomes  default  for  all 
future  transfers.  If  no  UIC  is  specified,  the  current  default  UIC  is 
used  (see  the  description  of  UIC,  following) .  Output  to  DOS/BATCH  is 
limited  to  DECtape  only.  Any  valid  RT-11  file  storage  device  may  be 
used  for  either  input  or  output  in  the  transfer. 


NOTE 

An  RT-11  DECtape  can  hold  more 
information  than  a  DOS/BATCH  or  RSTS-11 
DECtape.  Thus,  caution  should  be 
observed  in  copying  files  from  a  full 
RT-11  tape  to  a  DOS  DECtape  as  some 
information  may  not  transfer.  In  such  a 
case  an  error  message  will  be  printed 
and  the  transfer  will  not  be  completed. 

When  a  transfer  from  an  RT-11  device  to 
a  DOS  DECtape  occurs,  the  block  size  of 
the  file  may  increase.  However,  if  the 
file  is  later  transferred  back  to  an 
RT-11  device,  the  block  size  does  not 
decrease. 


To  transfer  a  file  from  a  DOS /BATCH  file- structured  device  (or  RSTS-11 
DECtape)  to  an  RT-11  device,  the  command  string  format  is: 
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*dev: f ilnam. ext=dev:  f ilnam. ext/S/s [UIC] 


where: 

dev: 

=  on  the  output  side,  any  valid  RT-11  device  (if 
that  device  is  not  file- structured,  f ilnam. ext  may 
be  omitted);  on  the  input  side,  DOS /BATCH  DECtape 
or  disk,  or  RSTS-11  DECtape. 

f ilnam. ext 

=  for  output,  any  valid  RT-11  filename  and 

extension;  for  input,  any  valid  DOS/BATCH 

(RSTS-11)  filename  and  extension. 

/s 

=  the  switch  from  Table  J-l  which  designates  a 
DOS/BATCII  (RSTS-11)  file- structured  device.  (This 
switch  MUST  be  included  in  the  command  line.) 

/s 

=  optionally  any  other  switch  (one  only)  from  Table 
J-l  (in  this  case,  /A  is  the  only  meaningful 
switch  which  could  be  chosen) ;  /A  indicates  an 
ASCII  transfer  is  to  be  performed  in  which  nulls 
and  rubouts  are  deleted;  if  /A  is  not  used,  the 
transfer  will  be  performed  word-for-word. 

[UIC] 

=  the  DOS/BATCH  user  identification  code  in  the 
format  [nnn,nnn]  where  nnn  represents  1  to  3  octal 
digits  less  than  or  equal  to  377  specifying  first 
the  user-group  number,  and  then  the  individual 
user  number;  this  code  may  be  placed  anywhere  on 
the  side  of  the  command  line  containing  the 
DOS /BATCH  device;  whenever  a  UIC  is  entered,  it 
becomes  the  default  for  any  further  DOS/BATCH 
transfers;  the  initial  default  value  is  [1,1] . 

NOTE 

A  UIC  need  not  be  indicated  in  any 
command  line  if  accessing  only  DECtape 
since  individual  users  do  not  "own" 
files  on  DECtape  under  DOS;  no  error 
will  occur  if  a  code  is  used,  however. 

To  transfer  files  from  an  RT-11  storage  device  to  a  DOS/BATCH  or 
RSTS-11  DECtape,  the  command  line  format  is  as  follows: 

*DTn : f i 1 nam . ext/S/s=de v : f ilnam . ext 

where: 


DTns 

=  a  valid  DOS/BATCH  (RSTS-11)  DECtape  assignment 
(only  DECtape  is  legal  for  output) . 

f ilnam. ext 

=  for  output,  any  valid  DOS/BATCH  (RSTS-11)  filename 
and  extension?  for  input,  any  valid  RT-11 

filename  and  extension. 

/s 

=  the  switch  from  Table  J-l  which  designates  a 
DOS /BATCH  (RSTS-11)  file-structured  device.  (This 
switch  MUST  be  included  in  the  command  line.) 
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/s  ■  optionally  any  other  switch  (one  only)  from  Table 

J-l  (in  this  case,  /A  is  the  only  meaningful 
switch  which  could  be  chosen) ;  /A  indicates  an 
ASCII  transfer  is  to  be  performed  in  which  nulls 
and  rubouts  are  deleted;  if  /A  is  not  used,  the 
transfer  will  be  performed  word-for-word. 

dev:  =  any  valid  RT-11  device. 

Examples : 

**D T 2  :  S 0 R T .  RBC/S  =  S0k'T.  RBC 

This  command  instructs  FILEX  to  transfer  a  file  called  SORT. ABC  from 
the  RT-11  system  device  to  a  DOS/BATCH  (or  RSTS-11)  formatted  DECtape 
on  unit  DT2 . 

*PP  :  =DT2 : TVPE.  FlL/S/ft 

This  command  allows  a  file  to  be  transferred  from  DOS/BATCH  (or 
RSTS-11)  DECtape  to  the  papertape  punch  under  RT-11.  The  transfer  is 
done  in  ASCII  mode. 

*DK  :  *.  *  =  RI<1 :  MflCRl.  MRC,'SC  280,  200  ] 

This  command  causes  the  file  MACR1 . MAC  from  the  DOS /BATCH  disk  on  unit 
1  which  is  stored  under  the  UIC  [200,200]  to  be  transferred  to  the 
RT— 11  device  DK.  [200,200]  becomes  the  default  UIC  for  any  further 
DOS /BATCH  operations. 


J.2.3  Transferring  Files  to  RT-11  from  DECsystero-10 

Files  may  be  transferred  to  RT-11  devices  from  a  DECsystem-10  DECtape 
whenever  a  foreground  job  is  not  running  (this  restriction  is  due  to 
the  fact  that  when  reading  DECsystem-10  files,  FILEX  accesses  the 
DECtape  control  registers  directly  rather  than  using  the  RT-11  DECtape 
control  handler) .  Output  may  be  to  any  valid  RT-11  device; 
DECsystem-10  DECtape  is  the  only  valid  input  device.  The  format  of 
the  command  line  is: 

*dev: filnam.ext=DTn: filnam.ext/T/s 


where : 


dev: 

=  any  valid  RT-11  device;  if  that  device  is  not 
file-structured,  the  filnam.ext  may  be  omitted. 

filnam.ext 

=  for  output  ,  any  valid  RT-11  filename  and 

extension;  for  .input,  any  valid  DECsystem-10 

filename  and  extension  (see  NOTE  below). 

DTn: 

=  a  valid  DECsystem-10  DECtape  assignment  (only 
DECtape  is  legal  for  input) . 

/T 

=  the  switch  from  Table  J-l  which  signifies  a 
DECsystem-10  file-structured  device.  When  using 
/T,  especially  with  /A,  the  time  of  day  clock  will 
lose  time.  It  should  be  examined  with  the  monitor 

TIME  command,  and  reset  if  necessary. 
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/a  =  any  other  switch  from  Table  J-l  which  specifies 

the  mode  of  transfer.  Only  one  additional  switch 
may  be  indicated  per  transfer;  /P  is  assumed  if 
no  other  mode  is  specified. 


NOTE 

RT-11  files  may  be  indirectly  converted 
to  DECsystem-10  format  by  running  RT-11 
FILEX  and  converting  the  files  to  DOS 
formatted  DEC tape,  and  then  running 
DECsystem-10  FILEX  to  read  the  DOS 
DECtape;  however,  it  is  currently  not 
possible  under  RT-11  to  convert  files 
directly  from  RT-11  to  DECsystem-10 
format . 


Examples  s 

*DT2 : STAND.  LIS  =  DT1 : STAND.  LIS/T/ft 

The  ASCII  file  STAND. LIS  is  converted  from  DECsystem-10  ASCII  format 
to  RT-11  ASCII  format  and  stored  under  RT-11  on  DECtape  2  as 
STAND. LIS. 

NOTE 

Transfers  from  DECsystem-10  DECtape  to 
RT-11  DECtape  may  cause  an  < UNUSED > 
block  to  appear  after  the  file  on  the 
RT-11  device.  This  is  a  result  of  the 
method  by  which  RT— 11  handles  the 
increased  amount  of  information  on  a 
DECsystem-10  DECtape. 


*SV : *.  NEW=DT8 : *. LIS/T 

This  command  indicates  that  all  files  on  DECsystem-10  DECtape  0  with 
the  extension  .LIS  are  to  be  transferred  to  the  RT-11  system  device 
(disk  or  DECtape)  using  the  same  filename  and  an  extension  of  .NEW. 
The  /P  switch  is  the  assumed  transfer  mode. 


J.2.4  Listing  Directories 

Device  directories  of  any  of  the  file-structured  devices  used  in.  a 
FILEX  transfer  can  be  listed  on  the  console  terminal.  The  following 
FILEX  command  lines  are  \iseds 

*dev:/L  for  RT-11 

*dev:/L/S  for  DOS /BATCH  (RSTS-11) 

*DTn:/L/T  for  DECsystem-10 
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dev:  =  disk  or  DECtape  (DK  is  assumed  if  no  device  is 

specified) . 

DTns  =  DECsystem-10  DECtape. 

A  =  the  switch  from  Table  J-l  which  indicates  a 

listing  is  desired  (/F  may  be  substituted  if  a 
"fast  listing"  is  preferred) . 

/S  =  the  switch  from  Table  J-l  which  designates  a 

DOS/BATCH  or  RSTS— 11  file— structured  device. 

/T  =  the  switch  from  Table  J-l  which  designates  a 

DECsystem-10  file-structured  device. 

Examples  s 


*RK1:, 

BADE* 

■'L/5 

.  svs 

1 

22-JUL-74 

MONLIB.  CIL 

175C 

22-JUL-74 

DU  1 1 

.  PAL 

45 

24-JUL-74 

VERIFV.  LDfl 

67C 

22- JUL-74 

C I  L  U  5 

.  L  D  A 

39 

22-JUL-74 

This  command  lists  the  complete  disk  directory  of  the  device  RK1.  The 
letter  "C"  following  the  file  size  on  a  DOS/BATCH  or  RSTS-11  directory 
listing  indicates  the  file  is  a  contiguous  file. 


*DT1 :  *.  PRL/L/S 

This  command  lists  all  files  with  the  extension  .PAL  which  are  on 
drive  1. 

*DT1 :  *.  */F/T 

All  files  on  DECsystem-10  formatted  DECtape  1,  regardless  of  filename 
or  extension,  are  listed;  a  fast  directory  is  requested  (/F)  in  which 
only  filenames  are  printed. 


J.2.5  Deleting  Files  from  DOS /BATCH  (RSTS-11)  DECtapes 

FILEX  may  be  used  to  delete  files  from,  and  zero  directories  of, 
DOS /BATCH  and  RSTS— 11  formatted  DECtapes.  The  format  of  these  command 
lines  is: 


*dev:filnam.ext/S/D  to  delete  a  file 

or 

*dev:/S/Z  to  zero  a  directory 

dev:/Z  ARE  YOU  SURE? 

where : 


dev:  =  DOS /BATCH  or  RSTS-11  DECtape. 

filnam.ext  =  a  valid  DOS/BATCII  (RSTS-11)  filename  and 
extension. 
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/S  =  the  switch  from  Table  J-l  which  designates  that 

the  device  is  DOE/BATCH  (RSTS-11)  file-structured. 

/D  =  the  switch  from  Table  J-l  which  designates  that  a 

file  is  to  be  deleted. 

/Z  -  the  switch  from  Table  J-l  which  designates  that  a 

directory  is  to  be  zeroed. 

Examples  s 

*DT8:*  PRL/D/S 


All  files  on  DECtape  0  with  the  extension  .PAL  are  deleted. 

*DT2  :  TRBLE.  OBJ/D/S 

The  file  TABLE. OBJ  is  deleted  from  the  DECtape  on  unit  2. 

*DT0 : /Z/S 

D T 0 : / 2  RRE  VOU  SURE  ?V 

The  DECtape  on  drive  0  is  initialized  in  DOS/BATCH  (RSTS-11)  format  so 
that  it  contains  no  files. 


J. 3  ERROR  MESSAGES 

Following  is  a  list  of  error  messages  that  may  occur  under  FILEX: 


Message  Meaning 


7FILNAM.EXT  ALREADY  EXISTS? 

An  attempt  was  made  to  create  the  named  file 
(filnam.ext)  on  a  DOS  DECtape  when  a  file 
already  existed  under  the  name  specified. 
Use  /D  to  delete  the  file,  and  retry  the 
trans fer. 

The  DOS /BATCH  user  identification  code  was 
not  in  the  form  [nnn,nnn] ,  where  each  nnn  is 
an  octal  number  less  than  or  equal  to 
377 (octal) . 

There  was  insufficient  main  storage  for 
buffers  and  input  list  expansion.  Try 
copying  files  one  at  a  time,  without  using 
the  "wild-card"  (*.*)  construction  on  input. 

There  was  no  room  in  the  directory  for  the 
filename  or  there  was  no  room  on  the  output 
device  for  the  file  (in  which  case  the 
filename  is  not  placed  in  the  output  device 
directory) . 

An  error  occurred  while  reading  or  looking  up 
the  directory  of  the  input  device,  or  the 


?BAD  PPM? 


?COR  OVR? 


?DRV  FULL? 


?DIR  ERR? 
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7FEATURE  NOT  IMP? 

?FG  ACTIVE? 

?FIL  NAM? 

?FIL  NOT  FND? 

?ILL  CMD? 


?ILL  DEV? 


?ILL  SWT? 

?IN  ERR? 
?NO  UFD? 

?OUT  ERR? 
?SWT  ERR? 


input  device  does  not  have  the  proper  file 
structure. 

An  operation  was  attempted  which  FILEX  cannot 
perform  (e.g.,  zeroing  an  RT-11  device). 

An  attempt  was  made  to  use  /T  when  a 
foreground  job  was  active.  The  transfer  is 
not  allowed  until  the  foreground  job  is 
terminated  and  unloaded  via  UNLOAD  FG. 

The  output  filename  was  invalid  or  null. 

The  input  file  was  not  found,  or  the 
"wild-card"  (*.*)  construction  matched  none 
of  the  existing  files. 

The  length  of  the  command  line  exceeded  72 
characters;  the  command  line  was  not  in 
proper  CSI  format;  the  UIC  exceeded  the 
allowed  number  of  characters  or  [  was  used 
without  ];  a  "wild-card"  (*.*)  construction 
was  used  on  a  non-file-structured  device;  no 
output  or  no  input  file  was  specified  for  a 
copy  operation,  or  more  than  one  filename 
construction  (devsfilnam.ext)  was  specified 
on  either  side  of  the  =*  (<)  sign. 

The  device  handler  was  not  found,  an  invalid 
device  name  was  used,  or  one  of  the  following 
was  attempted: 

RK  or  DT  was  not  used  for  DOS/BATCH 
(RSTS-11)  input  in  a  copy  operation; 

DT  was  not  used  for  DOS/BATCH  (RSTS-11) 
output  in  a  zero  or  delete  operation; 

DT  was  not  used  for  DOS/BATCH  (RSTS-11) 
output  in  a  copy  operation; 

DT  was  not  used  for  DECsystem-10  input 
in  any  operation. 

An  illegal  switch  was  used  in  a  command  line 
(e.g.,  a  switch  not  listed  in  Table  J-l) . 

A  device  error  occurred  on  input. 

The  specified  UFD  was  not  found  on  the  DOS 
input  disk. 

A  device  error  occurred  on  output. 

An  attempt  was  made  to  use  more  than  one  /S 
or  /T  switch  in  a  command  line  (only  one  is 
allowed) ;  an  attempt  wa3  made  to  use  more 
than  one  transfer  mode  switch  (/I,  /P,  /A)  or 
more  than  one  operation  switch  (/D,  /L,  /F, 

/Z)  in  a  command  line  (only  one  of  each  is 
allowed) . 
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SOURCE  COMPARE  (SRCCOM) 


The  RT-11  Source  Compare  program  (SRCCOM)  is  used  to  compare  two  ASCII 
files  and  to  output  any  differences  to  a  specified  output  device.  It 
is  particularly  useful  when  the  two  files  are  different  versions  of  a 
single  program,  in  which  case  SRCCOM  prints  all  the  editing  changes 
which  transpired  between  the  two  versions. 


K.l  CALLING  AND  USING  SRCCOM 
To  run  SRCCOM  type  the  command: 

R  SRCCOM 

followed  by  a  carriage  return  in  response  to  the  dot  printed  by  the 
Keyboard  Monitor?  the  CSI  prints  an  asterisk.  Then  enter  the  names 
of  the  files  which  are  to  be  compared  using  a  command  string  in  the 
following  format: 

dev : output=dev : inputl , dev : input2/s 


where: 


dev:  is  any  valid  device  specification. 

output  is  the  filename  and  extension  assigned  to  the  output 

file.  If  no  output  file  is  indicated,  output  is 
directed  to  the  terminal. 

inputl...  are  the  input  source  filenames  and  extensions  to  be 
compared. 

/s  is  one  of  the  switches  listed  in  Table  K-l. 


Source  files  are  examined  line  by  line  for  groups  of  lines  which 
match.  When  a  mismatch  occurs,  all  differences  are  output  until  n 
successive  lines  in  the  first  file  are  identical  to  n  lines  in  the 
second  file.  The  number  (n)  is  a  variable  which  the  user  can  set  with 
the  /L  switch. 
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K.1.1  Extensions 

No  default  extension  is  assigned  by  SRCCOM  to  the  output  file.  The 
default  extension  for  an  input  file  is  .MAC,  representing  a  source 
file  in  MACRO  language. 


K.1.2  Switches 

Command  switches  are  generally  placed  at  the  end  of  the  command  string 
but  may  follow  any  filename  in  the  string.  The  following  switches 
can  appear  in  the  command  string: 


Table  K-l 
SRCCOM  Switches 


Switch 

Meaning 

/B 

Compare  blank  lines.  Without  this  switch,  blank 
lines  are  ignored. 

/c 

Ignore  comments  (all  text  on  a  line  preceded  by  a 
semicolon)  and  spacing  (spaces  and  tabs) .  This 
switch  does  not  cause  a  line  consisting  entirely 
of  a  comment  to  become  a  blank  line,  and  therefore 
ignored  in  the  line  count. 

/F 

Include  form  feeds  in  the  output  file.  (Form 

feeds  are  still  compared  if  /F  is  not  used, 

but  they  are  not  included  in  the  output  of 
differences.) 

/H 

Type  list  of  switches  available  (help  text) .  No 
I/O  device  is  necessary  since  /H  always  prints  the 
help  text  on  the  terminal. 

/L:n 

Specify  the  number  of  lines  that  determines  a  match 
(n  is  an  octal  number  <=310) .  All  differences 
occurring  before  and  after  a  match  are  output.  In 
addition,  the  first  line  of  the  current  match  is 
output  after  the  differences  to  aid  in  locating 
the  place  within  each  file  at  which  the 
differences  occurred.  The  default  value  for  n  is 

3. 

/s 

Ignore  spaces  and  tabs. 

K.2  OUTPUT  FORMAT 


The  first  line  of  each  file  is  always  output  as  identification  and  is 
not  compared.  A  blank  line  is  then  printed,  followed  by  the 
differences  between  the  files,  in  the  following  format: 
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1)  1  FI LEA 

1)  A 
**** 

2) 1  FILEB 

2)  A 

********** 


%  FILES  ARE  DIFFERENT 


The  different  lines  are  listed  followed  by  a  reference  line  which  is 
the  same  for  both  files.  Note  the  example  below. 

The  following  example  uses  SRCCOM  to  compare  an  edited  file  and  its 
backup  version.  The  default  value  for  a  match  is  3  lines.  Blank 
lines  are  ignored  but  all  other  characters  are  compared. 

Following  the  example  is  a  coded  explanation  of  the  comparison. 


R  SRCCOM 

* R K 1  .LINK©.  FB,  LINK©.  BftK 

a  (  1)1  .TITLE  RTLINK  ROOT  CODE  X01-1 6 

\  2)1  .TITLE  RTLINK  ROOT  CODE  X01-15 


5  E  V  E  N  K  =  11452  ; MINIMUM  CORE  TO  STfiRT  LINKER 


.  MCftLL  .  CSISPC, .  CSIGEN, .  SETTOP, .  LOCK, .  UNLOCK 
SEVENK*  11500  ; JUST  BELOW  SK  RESIDENT 


.  MCflLL  .  CSISPC,  .  CSIGEN,  .  SETTOP,  .  LOCK,  .  UNLOCK 

.  GLOBL  RSWIT, RELPTR, FBTXT, OVLNUM, RELOVL, RLSTRT 
.  GLOBL  RELftDR, PNRELO, RELID1, RSIZ1, GVSIZ1, OVLCDE 

.  GLOBL  RSWIT, RELPTR, FBTXT, OVLNUM, RELOVL 
.  GLOBL  RELftDR,  PNRELO,  RE L  I  Dl,  RSIZl.,  0VSIZ1,  OVLCDE 

.  BLKW  ; CURRENT  REL  BLK  OVERLfiV  NUM 

.  BLKW  ; POINTER  TO  CURRENT  REL  BLK  LOCftTION 

.BLKW  ; POINTER  TO  CURRENT  REL  BLK  LOCftTION 

.  ASCII  /RT-11  LINK  X01-1 6/ 

.  ft SC  I  I  /  LOAD  MAP  / 

.  ft SC  I  I  /RT-11  LINK  X  0 1 - 1 5 / 

.  ASCII  /  LOAD  MAP  / 

. IF  DF  FB 

MOV  OBLK, RLSTRT  ;IND  START  OF  GVL  FOR  REL  BLK 

.  ENDC 

BR  1 $ 

BR  1 $ 


hfiles  are  different 
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A  Headers ,  consisting  of  the  first  line  of  each  file?  for 
identification  purposes, 

B  n)m.  A  notation  where  n  is  the  number  of  the  input  file,  and  m  is 
the  page  number  of  the  input  file  on  which  the  text  appears.  The 
right  column  lists  the  lines  in  the  files  which  are  different, 

C  Following  a  section  of  differences ,  a  line  identical  to  each  file 
is  output  for  reference  purposes, 

D  Indicates  that  the  files  are  different  (this  is  printed  on  the 
system  console,  not  in  the  output  file) , 


This  example  uses  the  /L:n  switch  and  sets  the  number  of  lines  that 
determines  a  match  to  2  lines.  The  first  two  columns  represent  the 
input  files: 


TEST  FILE  1 
LINE  C 
LINE  E 
LINE  C 
LINE  D 
LINE  F 
LINE  H 
LINE  I 
LINE  J 


TEST  FILE  2 
LINE  C 
LINE  D 
LINE  C 
LINE  E 
LINE  F 
LINE  G 
LINE  H 
LINE  I 
LINE  J 

The  files  are  compared  and  differences  listed  on  the  line  printer, 

*LP : =TEST1, TEST2/L : 2 

m  TEST  Flue  1 

2)1  TfcST  FILE  2 
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m 

LINE 

E 

n 

line 

c 

» 

LINE 

0 

LINE 

f 

i) 

LINE 

H 

**** 

2)1 

LINE 

0 

2) 

line 

c 

2) 

LINE 

E 

2) 

LINE 

f 

2) 

line 

s 

2) 

line 

H 

This  message  prints  on  the  terminal  indicating  that  the  files  are 
different. 

KFILE5  ft RE  DIFFERENT 


K. 3  ERROR  MESSAGES 

The  following  errors  may  be  reported  by  SRCCOM: 


Messages 
?COR  OVR? 

?IN  ERR? 

?OUT  ERR? 

? SWITCH  ERROR? 

?TOO  MUCH  DIFFERENCE? 


Meaning 


Not  enough  memory  to  hold  a  particular 
difference  section. 

A  hardware  error  occurred  in  reading 
input. 

A  hardware  error  occurred  in  writing 
output  file,  or  output  device  full. 

An  invalid  switch  was  found  or  a  switch 
other  than  /L  was  given  a  value. 

More  than  310  (octal)  lines  of 
difference  between  two  files  were  found. 
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The  PATCH  utility  program  is  used  to  make  code  modifications  to  memory 
image  (.SAV)  files,  including  overlay-structured  and  monitor  files. 
PATCH,  like  ODT,  can  be  used  to  interrogate,  and  then  to  change,  words 
or  bytes  in  the  file. 

PATCH  provides  eight  relocation  registers.  Before  changing  a  program 
with  PATCH,  copy  the  old  file  to  a  backup  file  with  PIP,  as  the  old 
file  is  modified  when  PATCH  is  used. 


L.l  CALLING  AND  USING  PATCH 
To  run  PATCH,  type  the  command: 

R  PATCH 

followed  by  the  RETURN  key  in  response  to  the  dot  printed  by  the 
monitor.  PATCH  prints  a  version  number  message: 

PATCH  VO 1-02 

and  then  prints  the  message: 

FILE  NAME  — 


In  response  to  the  asterisk,  enter  the  name  of  the  file  to  be 

modified,  using  the  following  format: 

de v : f i lnam . ext/M/O 

where : 

dev:  represents  an  optional  device  specification;  if 

not  specified,  DK:  is  assumed. 

filnam.ext  represents  the  name  of  the  file  which  is  to  be 

patched,  if  an  extention  is  not  indicated,  .SAV  is 
assumed. 

/M  must  be  used  if  the  file  is  an  RT-11  monitor  file. 

/O  must  be  used  if  the  file  is  an  over lay- structured 

file. 
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After  this  information  has  been  entered,  the  Command  String 
Interpreter  prints  an  asterisk  indicating  that  it  is  ready  to  accept  a 
command.  Note  that  /0  and  /M,  if  used,  must  be  specified  when  the 
file  name  is  typed;  they  are  not  legal  at  any  other  time. 


L.2  PATCH  COMMANDS 

Table  L-l  summarizes  the  PATCH  commands. 


Table  L-l 
PATCH  Commands 


Command 

Action 

Vr;nR 

Set  relocation  register  n  to  value  Vr. 

bsB 

Set  bottom  address  of  overlay  file  to  b. 

[s:]r,o/ 

Open  word  location  Vr  +  o  in  overlay 
segment  s. 

[s:]r,o\ 

Open  byte  location  Vr  +  o  in  overlay 
segment  s. 

<CR> 

Close  currently  open  word/by te. 

<LF> 

Close  currently  open  word/byte  and  open 
the  next  one. 

A 

t  or 

Close  currently  open  word/byte  and  open 
the  previous  one. 

@ 

Close  the  currently  open  word  and  open 
the  word  addressed  by  it. 

F 

Begin  patching  a  new  file. 

E 

Exit  to  RT-11  monitor. 

Explanations  of  each  command  follow.  An  example  of  the  use  of  the 
commands  is  provided  in  Section  L.3. 


L.2.1  Patch  a  New  File 

The  F  command  causes  PATCH  to  close  the  file  being  patched,  and  accept 
a  new  file  name  to  be  patched. 
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L.2.2  Exit  from  PATCH 

The  E  command  causes  PATCH  to  close  the  file  being  patched  and  return 
control  to  the  RT-11  monitor. 


L.2.3  Examine ,  Change  Locations  in  the  File 

For  a  non-overlay  file,  a  word  address  may  be  opened,  as  with  ODT,  by 
typing  j 

[Crelocation  register >,] offset/ 

At  this  point,  PATCH  will  type  out  the  contents  of  the  location  and 
wait  for  the  user  to  type  in  either  new  location  contents  (in  octal) 
or  another  command. 


In  an  overlay  file,  the  format  is: 

[<segment  number>:] [< relocation  register>,]offset/ 

Where  < segment  number >  is  the  overlay  segment  number  as  it  is  printed 
on  the  link  map  for  the  file.  If  it  is  omitted,  the  root  segment  is 
assumed. 

Similarly,  to  open  a  byte  address  in  file,  the  format  is: 

[<relocation  register >,] off set\ 
for  non  overlay  files,  or 


[<segment  number>:] [<relocation  register>,]offset\ 
for  overlay  files. 

Once  a  location  has  been  opened,  the  user  may  optionally  type  in  the 
new  contents  in  the  format: 


[<relocation  regis ter >, lvalue 


followed  by  one  of  these  control  characters: 


< carriage  return > 


<line  feed> 


t  or 


A 


@ 


Close  the  current  location  by  changing 
its  contents  to  the  new  contents  (if 
specified) ,  and  await  more  control 
input. 

Close  the  current  location,  and  open  the 
next  word/by te. 

Close  the  current  location,  and  open  the 
previous  word/byte. 

Close  the  current  word  location,  and 
open  the  word  addressed  by  it  (in  the 
same  segment  if  an  overlay  file) . 
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L.2.4  Set  Bottom  Address 

To  patch  an  overlay  file,  PATCH  must  know  the  bottom  address  at  which 
the  program  was  linked  if  it  is  different  from  the  initial  stack 
pointer.  This  is  the  case  if  the  program  sets  location  42  in  an 
.ASECT.  To  set  the  bottom  address,  type: 

<bottom  address >:B 

Note  that  the  B  command  must  be  issued  before  any  locations  are  opened 
for  modification. 


L.2.5  Set  Relocation  Registers 

The  relocation  registers  0-7  are  set,  as  with  ODT,  by  the  R  command. 
The  R  command  has  the  format: 

{relocation  value >; {relocation  register >R 

Once  one  of  the  eight  relocation  registers  has  been  set,  the 
expression: 

{relocation  regis ter >,{ octal  number > 
typed  as  part  of  a  command  will  have  the  value: 

{relocation  value>  +  {octal  number> 


L.3  EXAMPLES  USING  PATCH 

The  following  example  shows  how  to  patch  a  non-overlaid  file.  Assume 

the  following  program  (EXAM) : 

.MAIN,  N T*  1 1  MACRO  VM02-08  PACE  1 


1 

2 

3  020019  CRt 

4  000012  IF* 

5  000000'  iCSICT 

S  • MC ALL 

7  .NLIST 

8  000000  124  MSS  I  .ASCII 

9  .LIST 

10  00034  000403  STARTl  BR 

11  00036  .PRINT 

12  00044  EXIT  I  .EXIT 

13  000034)  .END 


19 

12 

MAIN 

.PRINT, .EXIT 
BEX 

/THIS  IS  A  SUCCESSFUL  P ATCH/«CR><LF» 

BEX 

EXIT 

«MSG 

START 


This  program  has  been  assembled  with  MACRO  and  linked  with  LINK; 
execution  causes  no  output  of  text: 


R  E  X  ft  (1 


L-4 


PATCH 


To  make  a  line  of  text  print  on  the  terminal,  PATCH  is  used  as 
follows : 


.  R  PATCH 

PATCH  V01-02 

FILE  NAME-- 
*  E  X  A  M .  SAV 
+1000; 0R 

*0, 24/  403  240 

*E 


Now  when  the  program  is  executed: 

. R  EXAM 

THIS  IS  A  SUCCESSFUL  PATCH 

The  next  example  demonstrates  a  similar  situation,  only  includes  an 
overlay  file.  These  programs  have  been  assembled  and  linked;  the 
output  of  both  operations  is  included: 


.MAIN,  HT*ii  MACRO  VM02-08  3-3EP-74  PAGE  1 

1 

2 


3 

000019 

CRs 

19 

4 

000012 

LM 

12 

9 

000007 

PC* 

X7 

6 

000000' 

•csect 

MAIN 

7 

.CSLOBL 

ENTRY, MSGl 

8 

•mcall 

•PRINT, .EXIT 

9 

•NLIST 

BEX 

10 

00000 

124  M3l» | 

•ASCII 

/THIS  IS  A  SUCCESSFUL  PaTCM/«CR>«LF> 

11 

00038 

124  MSS  1 1 

•ASCII 

/THIS  IS  AN  OVERLAY  PATCH/ 

12 

•  LIST 

BEX 

13 

00066 

000403  STARTI 

0K 

EXIT 

14 

00070 

•PRINT 

•  MSG 

IS 

00076 

004767  EXITS 

JSR 

PC, ENTRY 

000000G 

18 

00102 

•  EXIT 

17 

000069' 

•  ENO 

START 
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.MAIN,  ST-11  MACRO  VM02-08  3-SEP-74  PAGE  1 

1 

2 


a 

000019 

CR0 

15 

4 

000012 

CM 

12 

9 

000007 

PC« 

X7 

6 

0000001 

•  CSECT 

OVL 

7 

« M  C  A  C  C 

.print 

8 

• GCOBC 

MSG  1 

9 

• GLOBC 

ENTRY 

10 

00000 

000403  ENTRY! 

BR 

RETURN 

11 

00002 

.PRINT 

RMSGl 

12 

00010 

000207  RETURN! 

RTS 

PC 

13 

000001  • 

•  ENQ 

RT-ll  LINK 

PTCH  .SAV 

X03-18 

LOAD  MAP 

03-SEP-74 

SECTION  ADOR 

SIZE 

ENTRY 

ADDR  ENTRY 

ADDR 

entry 

AQOR 

,  ABS.  000000 
MAIN  001122 

001122 

000104 

MSG  1 

001157 

overlay  REGION 
OVC  0012S0 

000001 

000012 

segment 

entry 

000001 

001200 

TRANSFER  ADDRESS  •  (<5101210 
HIGH  LIMIT  •  001242 


Running  the  program  (PTCH)  produces  no  terminal  output: 

R  PTCH 


But  by  using  PATCH  to  modify  the  file  as  follows: 
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. R  PATCH 

PATCH  V01-02 

FILE  NAME-- 
*PTCH.  SftVVG 
*1230; 0R 

*1:0; 0 /  403  240 

*E 


the  following  line  results: 

R  P  T  C  H 

THIS  IS  AN  OVERLRV  PATCH 


L.4  PATCH  ERROR  MESSAGES 

Error  messages  which  may  occur  under  PATCH  follow. 


Message 

7ADDR  NOT  IN  SEG7 

7BAD  SWITCH? 

7BOTTOM  ADDR  WRONG? 


7INCORRECT  FILE  SPEC? 


7INSUFFICIENT  CORE? 


7INVALID  RELOC  REG? 

7INVALID  SEG  NO? 
7MUST  OPEN  WORD? 

7MUST  SPECIFY  SEG? 


Meaning 

The  address  is  not  in  the  specified 
segment. 

Typed  a  switch  other  them  /O  or  /M. 

The  bottom  address  specifed  or  contained 
in  location  42  of  an  overlay  file  is 
incorrect.  Specify  the  correct  one 
using  the  b:B  command. 

The  response  to  the  "FILE  NAME  — " 
message  was  not  of  the  correct  form. 
Try  again. 

PATCH  did  not  have  enough  memory  to  hold 
the  file's  device  handler  plus  the 
internal  "segment  table."  This  message 
should  not  occur. 

Tried  to  reference  a  relocation  register 
outside  the  range  0-7. 

The  segment  number  S:  does  not  exist. 

The  @  command  was  typed  when  a  byte 
location  was  open. 

The  address  referenced  is  not  in  the 
root  section;  a  segment  number  Ss  must 
be  used. 
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?N0  ADDR  OPEN? 

?NOT  IN  PROGR  BOUNDS? 
?ODD  ADDRESS? 

?ODD  BOTTOM  ADDR? 

7PROG  HAS  NO  SEGS? 

?READ  ERROR? 

? WRITE  ERROR? 


The  <line  feed>,  t  or  @  command  was 
typed  when  no  location  was  open* 

Tried  to  open  a  location  beyond  the  end 
of  the  file. 

Tried  to  open  a  word  address  which  was 
odd.  (Use  "\".) 

The  bottom  address  specified  or 
contained  in  location  42  of  an  overlay 
file  is  odd. 

The  file  specified  as  an  overlay  file  is 
not. 

File  I/O  error  in  reading. 

File  I/O  error  in  writing. 
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The  RT-11  PATCHO  program  is  used  to  correct  and  update  object  modules 
(files  output  by  the  assemblers  or  by  the  FORTRAN  compiler) .  It  is 
particularly  useful  when  making  corrections  to  routines  that  are  in 
.OBJ  format  for  which  the  source  files  are  not  available.  PATCHO 
cannot  be  used  to  patch  libraries  built  by  LIBR,  but  it  can  be  used  to 
patch  the  OBJ  modules  from  which  a  library  is  built. 


M.l  CALLING  AND  USING  PATCHO 
To  run  PATCHO  type  the  command: 

R  PATCHO 

in  response  to  the  dot  printed  by  the  Keyboard  Monitor.  When  PATCHO 
is  ready  to  accept  commands,  an  asterisk  is  printed.  The  standard 
RT-11  command  string  is  not  used  for  PATCHO.  Specific  commands 
(described  in  Section  M.2)  are  typed  in  response  to  the  asterisk. 

Type  CTRL  C  to  halt  PATCHO  at  any  time  and  return  control  to  the 
monitor.  To  restart  PATCHO,  type  R  PATCHO  or  the  REENTER  command  in 
response  to  the  monitor's  dot. 


M.  2  PATCHO  COMMANDS 

There  are  nine  commands  and  arguments  accepted  by  PATCHO.  All 
arguments  to  a  command  must  be  separated  from  the  command  name  by  one 
or  more  spaces  (e.g.,  POINT  TOP  is  acceptable,  POINTTOP  is  not). 
Commands  are  terminated  by  a  carriage  return. 


M.2.1  OPEN  Command 

The  OPEN  command  sets  input  and  output  file  names.  When  the  command 
is  given,  PATCHO  prints: 

ENTER  INPUT  FILE* 
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on  the  console  terminal ,  and  waits  for  a  standard  RT-11  device  and 
file  specification  to  be  entered  (devsfilnam.ext)  .  After  the  input 
specification  is  given ,  followed  by  a  carriage  return ,  PATCHO  responds 
with: 


ENTER  OUTPUT  FILE* 

A  device  and  file  specification  (followed  by  a  carriage  return)  for 
the  desired  output  file  is  now  accepted  from  the  console. 


NOTE 

There  is  no  default  extension. 
Therefore ,  the  user  must  explicitly 
specify  the  filename  and  extension. 


Example: 


♦OPEN  <CR> 

ENTER  I NPUT  F I LE  *RK 1 : GTS ♦ OBJ 
ENTER  OUTPUT  FILE  ♦RK 1 ♦ NEWOTS ♦ OBJ 


M.2.2  POINT  Command 

The  POINT  command  locates  an  object  module  of  a  given  name  (used  with 
concatenated  object  modules)  and  prepares  it  for  subsequent  WORD, 
BYTE,  or  DUMP  operations.  POINT  takes  one  argument — the  module  name 
to  be  located. 

Example: 


♦POINT  Oil NIT 


M.  2 . 3  WORD  Command 

The  WORD  command  modifies  a  given  word  in  an  object  module.  There  may 
be  several  arguments  to  the  command,  entered  as  illustrated  below  (the 
BYTE  command  is  also  included  since  its  arguments  are  exactly  the 
same;  refer  to  Section  M.2.4) : 


Address  Specifier  Value  Specifier 

WORD  A  CSECT  +  OFFSET  =  C NAME  OF  f 

BYTE  J  NAME  <  %  /CSECT  OR  (  -  ?  OFFSET 

J  L  J GLOBAL  SYMBOL^  J 

where  in  the  Address  Specifier: 

1.  CSECT  is  the  name  of  the  CSECT  which  contains  the  word  to  be 
modified.  The  CSECT  must  be  present  in  the  current  module 
(the  one  specified  in  the  POINT  command) . 
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The  CSECT  argument  is  optional;  if  omitted,  the  blank  CSECT 
is  assumed.  To  represent  a  CSECT  name  which  contains 
embedded  blanks  (.  ABS.),  a  backarrow  (SHIFT  0)  or  underscore 
character  should  be  used  in  place  of  each  embedded  blank. 

2.  OFFSET  is  the  octal  location  within  the  CSECT  that  is  to  be 
modified.  OFFSET  must  be  present. 

3.  =  is  a  delimiter  and  must  be  present. 

In  the  Value  Specifier: 

1.  If  #  is  used,  the  absolute  value  of  the  OFFSET  in  the  Value 
Specifier  field  is  placed  in  the  target  location. 

For  example: 

♦WORD  PRQG+24=#4 

This  command  patches  location  24  in  CSECT  PROG  to  contain  the 
value  4. 

2.  If  %  is  used,  displaced  relocation  is  generated  on  the  Value 
Specifier.  This  mode  is  used  for  PC-relative  references. 
For  example: 

♦  W  0  R  D  P  R  0  G + 2  4 %  P  R  0  G 1  +  2  4 

This  command  patches  PROG+24  to  contain  the  value: 


Address  (PROG1+24) -Address  (PROG+26) 

3. ’  If  neither  #  or  %  are  specified,  the  address  of  the  Value 

Specifier  is  placed  in  the  target  location.  For  example: 

♦WORD  PR0G+24=14 

This  causes  the  word  at  PROG+24  to  contain  the  address  of  the 
word  at  PROG+14,  while: 

♦  W  0  R  D  P  R  0  G + 2  4  ~  S  Y  M  B  0  L + 0 

causes  the  word  at  PROG+24  to  contain  the  address  of  the 
global  symbol  "SYMBOL". 

4.  GLOBAL  is  optional  and  is  the  name  of  a  global  symbol  whose 
value  (address)  is  to  be  used  in  the  word  to  be  modified. 

5.  The  characters  +  or  -  are  optional  and  indicate  the  sign  of 
the  following  OFFSET.  Either  a  +  or  a  -  must  be  present  if 
an  OFFSET  is  indicated. 


M.2.4  BYTE  Command 

The  BYTE  command  modifies  a  given  byte  in  an  object  module.  The 
arguments  are  the  same  as  for  WORD,  explained  in  Section  M.2.3. 


M-3 


PATCHO 


Example : 


KBYTE  CSECTA+21«#101 

The  byte  in  CSECTA  whose  offset  is  21  is  patched  to  contain  octal  101 
(ASCII  "A”). 


M.  2 . 5  DUMP  Command 

The  DUMP  command  prints  the  contents  of  the  object  module  currently 
being  pointed  to  and  causes  an  automatic  POINT  to  the  next  module  in 
the  input  file,  if  any.  Use  the  monitor  SET  LP  CR  command  first  for 
correct  output  format. 


NOTE 

LIST  and  DUMP  go  to  LP:  (lineprinter) 

by  default.  If  the  user  wants  LIST  and 
DUMP  to  go  to  the  terminal,  he  must 
execute  an  ASSIGN  TT:6  command  before 
typing  R  PATCHO. 

Refer  to  Section  M.4  for  an  example  of  the  DUMP  command. 


M.2.6  LIST  Command 

The  LIST  command  lists  the  names  of  all  the  object  modules  in  the 
input  file  in  the  order  in  which  they  appear  in  the  file.  A  POINT 
command  should  be  given  after  the  LIST  command  to  assure  that 
PATCHO  is  positioned  at  the  desired  module  for  the  next  operation. 
LIST  lists  the  names  of  all  object  modules  in  a  file  without  changing 
the  module  being  pointed  to. 

Refer  to  Section  M.4  for  an  example  of  the  LIST  command. 


M.2.7  EXIT  Command 

The  EXIT  command  returns  to  the  operating  system  terminating  a  patch 
session  and  closing  a  file.  The  EXIT  command  takes  no  argument.  As 
the  EXIT  command  is  executed,  ENTER  CHECKSUM:-  -  -  is  displayed.  The 
user  should  type  a  six-digit  octal  number  corresponding  to  the 
appropriate  checksum  for  the  patch  (if  any) .  If  the  checksum  does  not 
match,  an  error  message  appears  indicating  a  possible  typing  error. 
See  the  example  in  Section  M.2.8. 


M. 2 . 8  DEC  Command 

The  DEC  command  is  used  when  the  proper  checksum  for  the  patch  being 
made  is  unknown.  If  a  DEC  command  is  issued  during  a  patch  session, 
the  EXIT  command  is  automatically  modified  to  display: 
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ENTER  CHECKSUM: 

followed  by  the  correct  checksum  for  the  patch  just  completed.  The 
checksum  computed  by  PATCHO  is  derived  from  all  of  the  commands 
entered  during  the  session,  thereby  providing  a  safeguard  against 
typographical  errors.  If  the  DEC  command  is  used,  it  should  be  the 
first  command  given. 

♦  DEC 
♦EXIT 

ENTER  CHECKSUM:  25767 


M.2.9  HELP  Command 

The  HELP  command  prints  an  explanation  of  PATCHO  commands.  The  HELP 
command  takes  no  arguments. 


M. 3  PATCHO  LIMITATIONS 

Note  the  following  limitations  on  the  use  of  PATCHO: 

1.  PATCHO  only  works  with  object  modules  or  concatenated  object 
modules,  not  with  libraries. 

2.  PATCHO  always  copies  its  input  file  to  its  output  file  as  it 
makes  changes. 

3.  As  a  consequence  of  2  (above)  the  POINT  command  can  only  be 
used  to  point  to  modules  that  physically  follow  the  current 
module  in  the  input  file. 

4.  If  changes  are  being  made  to  a  file,  PATCHO  must  be  given  an 
EXIT  command  when  all  the  changes  are  complete  in  order  to 
assure  that  the  entire  input  is  copied  to  the  output  (i.e., 
CTRL  C  should  not  be  used) . 

5*  The  LIST  and  DUMP  commands  do  not  work  in  an  8K  system  (12K 
is  required) .  An  ERROR  30  occurs  if  this  is  violated. 


M.4  EXAMPLES 


The  following  is  an  example  of  the  PATCHO  command  LIST  in  which  a  few 
of  the  names  of  object  modules  in  the  library  file  (OTS.OBJ)  are 
listed: 


♦  LIST 

OBJECT  MODULES! 

|*RS9 

I VEC 

IVECP 

IPVEC 

FVEC 

fvecR 
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mvec 

ovec 

OVECM 

O^VEC 

I.VEC 

Lvecp 

LPVEU 

ERRS 

AOTS 

OTINIT 

The  next  example  is  a  sample  of  output  produced  by  the  PATCHO  DUMP 
Command.  The  module  is  dumped  by  formatted  binary  block. 

♦DUMP 


DUMP  op  MODULE  LPS0 


BLOCK  TYPE  GSD 


GLOBAL 

USAGE 

DEFINED 

RELOC 

EXTERNAL 

SIZE/ADRS 

LPS0 

MOD  NAME 

NO 

NO 

NO 

0 

.  ABS. 

CSECT 

YES 

NO 

NO 

0 

errarg 

GLOBAL 

NO 

NO 

YES 

0 

ERRPDL 

GLOBAL 

NO 

NO 

YES 

0 

ERRSYN 

GLOBAL 

NO 

NO 

YES 

0 

BLOCK  ' 

global 

TYPE  GSD 
USAGE 

DEFINED 

RELOC 

EXTERNAL 

SIZE/ADRS 

EVAL 

global 

NO 

NO 

yes 

0 

• 

BLOCK  TYPE  GSD 
GLOBAL  USAGE 

DEFINED 

RELOC 

EXTERNAL 

SIZE/ADRS 

USE 

GLOBAL 

YES 

YES 

YES 

104 

•  A  BS , 

TRAN  ADR 

YES 

NO 

NO 

1 

BLOCK  TYPE  GSD  END 


BLOCK  TYPE  RLD 

ADDRESS  RLD  TYPE  GLOBAL  OFFSET 


1772  LCTR  DEF 


0 


BLOCK  TYPE  TXT 
ADDRESS  CONTENTS 

0  0  0  0 

2  0  0  0 

4  0  0  0 

6  0  0  0 

10  0  0  0 

12  0  0  0 


« 

• 

1476  12602  202  25 

1500  12600  200  25 

1502  207  207  0 

BLOCK  TYPE  MOD  END 
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M.5  PATCHO  ERROR  MESSAGES 

Message  Explanation 


?BAD  CHECKSUM? 

A  formatted  binary  block  in  the  input 
file  has  a  checksum  which  does  not  agree 
with  that  calculated  for  its  contents. 

?BAD  OBJ? 

The  input  file  contains  information 
which  cannot  be  interpreted  as  an  object 
module. 

?DUMP  ERROR? 

An  input/output  error  occurred  while 
dumping  a  module. 

? ILLEGAL  COMMAND? 

A  command  line  was  not  recognized ,  or  it 
was  not  in  the  proper  format  for  the 
particular  command. 

?BAD  PATCH? 

Checksum  entered  on  exit  does  not  agree 
with  that  calculated  by  PATCHO  (the 
patch  was  made  as  specified) ,  This 
probably  indicates  a  typing  error. 

?MODULE  NOT  FOUND? 

The  module  requested  in  a  POINT  command 
was  not  found  in  the  input  file  between 
the  position  of  the  file  at  the  time  of 
the  point  and  the  end. 

?MORE  THAN  15  CHANGES? 

Too  many  changes  have  been  specified  for 
a  particular  module.  The  patch  should 
be  broken  up  into  several  steps. 

?MORE  THAN  5  CSECTS  REQUIRE 

CHANGE? 

An  attempt  has  been  made  to  patch 
locations  in  too  many  different  CSECTS. 
The  patch  should  be  made  in  several 
steps. 

?NO  FILE  OPEN? 

An  attempt  was  made  to  use  a  command 
other  than  "DEC”  or  "HELP"  before  an 
OPEN  command  was  issued. 

?OFFSET? 

The  offset  supplied  in  a  WORD  or  BYTE 
command  is  not  an  octal  number ,  or  is  in 
improper  format. 

?OUTPUT  ERROR? 

A  hardware  error  (or  possibly  a 
write-lock  condition)  occurred  while 
attempting  to  write  the  output  file. 

? OUTPUT  FILE  TOO  SMALL? 

The  space  allocated  to  the  output  file 
is  too  small.  This  may  be  corrected  by 
compressing  the  device  with  PIP  (if 
enough  total  space  is  free  on  the 
device) ,  or  by  using  another  device  for 
output. 
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M.5.1  Run-Time  Error  Messages 

Because  PATCHO  is  a  FORTRAN  program,  run-time  error  messages  may 
occur.  To  find  a  complete  explanation  of  each  run-time  error  refer  to 
the  RT-11  FORTRAN  COMPILER  AND  OBJECT  TIME  SYSTEM  USER'S  MANUAL 
(DEC-ll-LRFPA-A— D) .  Listed  below  are  four  of  the  most  important 
run-time  error  messages  which  may  be  encountered. 


23 

FATAL 

HARDWARE  I/O  ERROR 

A  hardware  error  has  been  detected  during 
operation. 

an 

I/O 

28 

FATAL 

OPEN  FAILED  FOR  FILE 

A  file  could  not  be  found. 

29 

FATAL 

NO  ROOM  FOR  DEVICE  HANDLER 

There  is  not  enough  free  memory 

accommodate  a  specific  device  handler. 

left 

to 

30 

FATAL 

NO  ROOM  FOR  BUFFERS 

There  is  not  enough  free  memory  left  to 
required  I/O  buffers. 

set 

up 
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DISPLAY  FILE  HANDLER 


This  appendix  describes  the  assembly  language  graphics  support 
provided  under  RT-11  for  the  GT40,  GT44,  and  DECLab-11  display 

hardware  systems. 

The  following  manuals  are  suggested  for  additional  references 
For  GT40  users: 

1.  GT40  USER'S  GUIDE  (DEC-ll-HGTGA-A-D) 

For  GT44  users: 

1.  GT44  USER'S  GUIDE  (DEC-11-HGT44-A-D) 


For  DECLab-11  users: 

1.  VT-11  GRAPHICS  DISPLAY  PROCESSOR  MANUAL  (DEC-ll-HVGTA-A-D) 

2.  RT-11  BASIC  REFERENCE  MANUAL  (DEC-ll-LBACA-B-D) 


N.l  DESCRIPTION 

The  GT40 ,  GT44 ,  and  DECLab-11  have  hardware  configurations  that 
include  a  display  processor  and  CRT  (cathode  ray  tube)  display.  The 
GT44  has  a  17-inch  tube;  the  GT40  and  DECLab-11  use  a  12-inch  tube. 
Both  systems  are  equipped  with  light  pens  and  hardware  character  and 
vector  generators,  and  are  capable  of  high-quality  graphics.  The 
Display  File  Handler  supports  this  graphics  hardware  at  the  assembly 
language  level  under  the  RT-11  monitor. 


N.1.1  Assembly  Language  Display  Support 

The  Display  File  Handler  is  not  an  RT-11  device  handler,  since  it  does 
not  use  the  I/O  structure  of  the  RT-11  monitor.  For  example,  it  is 
not  possible  to  use  PIP  to  transfer  a  text  file  to  the  display  via  the 
Display  File  Handler.  Rather,  the  Display  File  Handler  provides  the 
graphics  programmer  the  means  for  the  display  of  graphics  files  and 
the  easy  management  of  the  display  processor.  Included  in  its 
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capabilities  are  such  services  as  interrupt  handling,  light  pen 
support,  tracking  object,  and  starting  and  stopping  of  the  display 
processor. 

The  Display  File  Handler  manages  the  display  processor  by  means  of  a 
base  segment  (called  VTBASE)  which  contains  interrupt  handlers,  an 
internal  display  file  and  some  pointers  and  flags.  The  display 
processor  cycles  through  the  internal  display  file;  any  user  graphics 
files  to  be  displayed  are  accessed  via  display  subroutine  calls  from 
the  Handler's  display  file.  In  this  way,  the  Display  Pile  Handler 
exerts  control  over  the  display  processor,  relieving  the  assembly 
language  user  of  the  task. 

Through  the  Display  File  Handler,  the  programmer  can  insert  and  remove 
calls  to  display  files  from  the  Handler's  internal  display  file.  Up 
to  two  user  files  may  be  inserted  at  one  time,  and  that  number  may  be 
increased  by  re-assembling  the  Handler.  Any  user  file  inserted  for 
display  may  be  blanked  (the  subroutine  call  to  it  bypassed)  and 
unblanked  by  macro  calls  to  the  Display  File  Handler. 

Since  the  Handler  treats  all  user  display  files  as  graphics 
subroutines  to  its  internal  display  file,  a  display  processor 
subroutine  call  is  required.  This  is  implemented  with  software,  using 
the  display  stop  instruction,  and  is  available  for  user  programs. 
This  instruction  and  several  other  extended  instructions  implemented 
with  the  display  stop  instruction  are  described  in  Section  N.3. 

The  facilities  of  the  Display  File  Handler  are  accessed  through  a 
library  of  macros  (VTMAC)  which  generate  calls  to  a  set  of  subroutines 
in  VTLIB.  VTMAC  is  the  MACRO  library,  and  its  call  protocol  is 
similar  to  that  of  the  RT-11  macros.  The  expansion  of  the  macros  is 
shown  in  Section  N.6.  VTMAC  also  contains,  for  convenience  in 
programming,  the  set  of  recommended  display  processor  instruction 
mnemonics  and  their  values.  The  mnemonics  are  listed  in  Section  N.7 
and  are  used  in  the  examples  throughout  this  appendix. 

VTCAL1  through  VTCAL4  are  the  set  of  subroutines  which  service  the 
VTMAC  calls.  They  include  functions  for  display  file  and  display 
processor  management.  These  are  described  in  detail  in  Section  N.2. 
VTCALl  through  VTCAL4  are  currently  constructed,  along  with  the  base 
segment  VTBASE,  as  a  library  of  (five)  modules,  called  VLIB. 


N.1.2  Monitor  Display  Support 

The  RT-11  monitor,  under  Version  2,  directly  supports  the  display  as 
console  device.  A  keyboard  monitor  command,  GT  ON  (GT  OFF)  described 
in  Section  2.7.1,  permits  the  selection  of  the  display  as  console 
device.  Selection  results  in  the  allocation  of  approximately  1.25K 
words  of  memory  for  text  buffer  and  code.  The  buffer  holds 
approximately  2000  characters. 

The  text  display  includes  a  blinking  cursor  to  indicate  the  position 
in  the  text  where  a  character  is  added.  The  cursor  initially  appears 
at  the  top  left  corner  of  the  text  area.  As  lines  are  added  to  the 
text  the  cursor  moves  down  the  screen.  When  the  maximum  number  of 
lines  are  on  the  screen,  the  top  line  is  deleted  from  the  text  buffer 
when  the  line  feed  terminating  a  new  line  is  received.  This  causes 
the  appearance  of  "scrolling",  as  the  text  disappears  off  the  top  of 
the  display. 
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When  the  maximum  number  of  characters  have  been  inserted  in  the  text 
buffer,  the  scroller  logic  deletes  a  line  from  the  top  of  the  screen 
to  make  room  for  additional  characters.  Text  may  appear  to  move 
(scroll)  off  the  top  of  the  screen  while  the  cursor  is  in  the  middle 
of  a  line. 

The  Display  File  Handler  can  operate  simultaneously  with  the  scroller 
program,  permitting  graphic  displays  and  monitor  dialogue  to  appear  on 
the  screen  at  the  same  time.  It  does  this  by  inserting  its  internal 
display  file  into  the  display  processor  loop  through  the  text  buffer. 

Four  scroller  control  characters  provide  the  user  with  the  capability 
of  halting  the  scroller,  advancing  the  scrolling  in  page  sections,  and 
printing  hard  copy  from  the  scroller.  These  are  described  in  Chapter 


NOTE 

The  scroller  logic  does  not  limit  the 
length  of  a  line,  but  the  length  of  text 
lines  affects  the  number  of  lines  which 
may  be  displayed,  since  the  text  buffer 
is  finite.  As  text  lines  become  longer, 
the  scroller  logic  may  delete  extra 
lines  to  make  room  for  new  text, 
temporarily  decreasing  the  number  of 
lines  displayed. 


N.2  DESCRIPTION  OF  GRAPHICS  MACROS 

The  facilities  of  the  Display  File  Handler  are  accessed  through  a  set 
of  macros,  contained  in  VTMAC,  which  generate  assembly  language  calls 
to  the  Handler  at  assembly  time.  The  calls  take  the  form  of 
subroutine  calls  to  the  subroutines  in  VTLIB.  Arguments  are  passed  to 
the  subroutines  through  register  0  and,  in  the  case  of  the  .TRACK 
call,  through  both  register  0  and  the  stack. 

This  call  convention  is  similar  to  Version  1  RT-11  I/O  macro  calls, 
except  that  the  subroutine  call  instruction  is  used  instead  of  the  EMT 
instruction.  If  a  macro  requires  an  argument  but  none  is  specified, 
it  is  assumed  that  the  address  of  the  argument  has  already  been  placed 
in  register  0.  The  programmer  should  not  assume  that  R0  is  preserved 
through  the  call. 


N.2.1  .BLANK 

The  .BLANK  request  temporarily  blanks  the  user  display  file  specified 
in  the  request.  It  does  this  by  by-passing  the  call  to  the  user 
display  file,  which  prevents  the  display  processor  from  cycling 
through  the  user  file,  effectively  blanking  it.  This  effect  can  later 
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be  cancelled  by  the  .RESTR  request,  which  restores  the  user  file. 
When  the  call  returns,  the  user  is  assured  the  display  processor  is 
not  in  the  file  that  was  blanked. 

Macro  Call:  .BLANK  .faddr 

where:  .faddr  is  the  address  of  the  user 

display  file  to  be  blanked. 

Errors : 

No  error  is  returned.  If  the  file  specified  was  not  found  in  the 
Handler  file  or  has  already  been  blanked,  the  request  is  ignored. 


N.2.2  .CLEAR 

The  .CLEAR  request  initializes  the  Display  File  Handler,  clearing  out 
any  calls  to  user  display  files  and  resetting  all  of  the  internal 
flags  and  pointers. 

After  initialization  with  • LNKRT  (Section  N.2.4),  the  .CLEAR  request 
can  be  used  any  time  in  a  program  to  clear  the  display  and  to  reset 
pointers.  All  calls  to  user  files  are  deleted  and  all  pointers  to 
status  buffers  are  reset.  They  must  be  re-inserted  if  they  are  to  be 
used  again. 

Macro  Call:  .CLEAR 

Errors : 

None. 

Example : 

This  example  uses  a  .CLEAR  request  to  initialize  the  Handler,  then 
later  uses  the  .CLEAR  to  re-initialize  the  display.  The  first  .CLEAR 
is  used  for  the  case  when  a  program  may  be  restarted  after  a  CTRL  C  or 
other  exit. 


RSTRT 

#20000,  MM 


exit 

RSTRTl 

111 


HR 

BIS 

.UNLNK 

.LNKRT 

•CLEAR 

•XNSRT 

.TTYXN 

CMRB 

BNE 

.CLEAR 

.XNSRT 


#FILEi 

#12, R0 

IS 

#FXLE2 


{  SET  RENTER  BIT  IN  J3W 
(CLEARS  LINK  F LAC  FOR  RESTART 
| SET  UP  VECTORS,  START  DISPLAY 
UNITIALIZE  HANDLER. 

{DISPLAY  A  PICTURE 
| WAIT  FOR  A  KEY  STRIKE 
{LINE  FEED? 

{NO, LOOP 

{YES,  CLEAR  DISPLAY 
{DISPLAY  NEW  PICTURE 


FILE  1 1  POINT 
0 

500 

L0N6V 

5001INTX 

0 

DRET 

0 


{AT  POINT  (0,500) 

{DRAW  A  LINE 
{TO  (500,500) 
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FILE*!  POINT 


I  AT  POINT  (500,0) 


500 

0 

LONG  V 
01INTX 
500 
ORET 
0 


I  ORAN  A  LINE 
I  TO  (500,500) 


.END  EX1 


N.2.3  . INSRT 

The  .INSRT  request  inserts  a  call  to  the  user  display  file  specified 
in  the  request  into  the  Display  File  Handler's  internal  display  file. 
.INSRT  causes  the  display  processor  to  cycle  through  the  user  file  as 
a  subroutine  to  the  internal  file.  The  handler  permits  two  user  files 
at  one  time.  The  call  inserted  in  the  handler  looks  like  the 
following: 


DJSR 

.+4 

. f addr 


; DISPLAY  SUBROUTINE 
; RETURN  ADDRESS 
j SUBROUTINE  ADDRESS 


The  call  to  the  user  file  is  removed  by  replacing  its  address  with  the 
address  of  a  null  display  file.  The  user  file  is  blanked  by  replacing 
the  DJSR  with  a  DJMP  instruction,  bypassing  the  user  file. 

Macro  Calls  .INSRT  .faddr 


where :  . faddr  is  the  address  of  the  user 

display  file  to  be  inserted 


Errors : 


The  .INSRT  request  returns  with  the  C  bit  set  if  there  was  an  error  in 
processing  the  request.  An  error  occurs  only  when  the  Handler's 
display  file  is  full  and  cannot  accept  another  file.  If  the  user  file 
specified  exists,  the  request  is  not  processed.  Two  display  files 
with  the  same  starting  address  cannot  be  inserted. 

Example : 

See  the  examples  in  Sections  N.2.2  and  N.2.4. 


N.2.4  . LNKRT 

The  .LNKRT  request  sets  up  the  display  interrupt  vectors  and  possibly 
links  the  Display  File  Handler  to  the  scroll  text  buffer  in  the  RT-11 
monitor.  It  must  be  the  first  call  to  the  Handler,  and  is  used 
whether  or  not  the  RT— 11  monitor  is  using  the  display  for  console 
output  (i.e.,  the  KMON  command  GT  ON  has  been  entered). 

The  .LNKRT  request  used  with  the  Version  2  RT-11  monitor  enables  a 
display  application  program  to  determine  the  environment  in  which  it 
is  operating.  Error  codes  are  provided  for  the  situations  where  there 
is  no  display  hardware  present  on  the  system  or  the  display  hardware 
is  already  being  used  by  another  task  (e.g.,  a  foreground  job  in  the 
Foreground/Background  version) . 
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The  existence  of  the  monitor  scroller  and  the  size  of  the  Handler's 
subpicture  stack  are  also  returned  to  the  caller.  If  a  previous  call 
to  .LNKRT  was  made  without  a  subsequent  .UNLNK,  the  .LNKRT  call  is 
ignored  and  an  error  code  is  returned. 

Macro  Call:  .LNKRT 

Errors : 

Error  codes  are  returned  in  RO ,  with  the  N  condition  bit  set. 


Code 

Meaning 

-1 

No  VT11  display  hardware  is 
present  on  this  system. 

-2 

VT11  hardware  is  presently 
in  use. 

-3 

Handler  has  already  been 
linked. 

On  completion  of  a  successful  .LNKRT  request,  RO  will  contain  the 
display  subroutine  stack  size,  indicating  the  depth  to  which  display 
subroutines  may  be  nested.  The  N  bit  will  be  zero. 

If  the  RT-11  monitor  scroll  text  buffer  was  not  in  memory  at  the  time 
of  the  .LNKRT,  the  C  bit  will  be  returned  set.  The  KMON  commands 
GT  ON  and  GT  OFF  cannot  be  issued  while  a  task  is  using  the  display. 

Example : 


STARTl  .LNKRT 

SMI  ERROR 

BCS  CONT 

.SCROL  »SBUF 

CONTI  ,  INSRT  PPILEl 

ISt  .TTYIN 

CURB  #12, R0 

8NE  II 

.UNLNK 
.EXIT 

3BUFI  .Byte  5 

.BYTE  7 

.WORD  1000 


ILINK  TO  MONITOR 
I  ERROR  DOING  LINK 
I  NO  SCROLL  IF  C  SET 
I  ADJUST  SCROLL  PARAMETERS 
IDISPLAY  A  PICTURE 
I  WAIT  FOR  KEY  STRIKE 
I  LINE  FEE07 
I  NO ,  LOOP 

| YES*  UNLINK  AND  EXIT 


I  LINE  COUNT  OF  5 
IINTENSITY  7 ( SCALE  OF  i-8) 
f POSITION  OF  TOP  LINE 


FILEtl  POINT 
500 
500 

PuAB 

.ASCII  /THIS  IS 
.EVEN 
ORET 
0 


|  AT  POINT  (500.500) 

IDISPLAY  SOME  TEXT 
FILEI.  TYPE  CR  TO  EXIT/ 


ERROR  I  Error  routine 
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N.2.5  .LPEN 

The  .LPEN  request  transfers  the  address  of  a  light  pen  status  data 
buffer  to  VTBASE.  Once  the  buffer  pointer  has  been  passed  to  the 
Handler,  the  light  pen  interrupt  handler  in  VTBASE  will  transfer 
display  processor  status  data  to  the  buffer,  depending  on  the  state  of 
the  buffer  flag. 

The  buffer  must  have  seven  contiguous  words  of  storage.  The  first 
word  is  the  buffer  flag,  and  it  is  initially  cleared  (set  to  zero)  by 
the  .LPEN  request.  When  a  light  pen  interrupt  occurs,  the  interrupt 
handler  transfers  status  data  to  the  buffer  and  then  sets  the  buffer 
flag  non-zero.  The  program  can  loop  on  the  buffer  flag  when  waiting 
for  a  light  pen  hit  (although  doing  this  will  tie  up  the  processor, 
and  in  a  Foreground/Background  environment,  timed  waits  would  be  more 
desirable).  No  further  data  transfers  take  place,  despite  the 
occurrence  of  numerous  light  pen  interrupts,  until  the  buffer  flag  is 
again  cleared  to  zero.  This  permits  the  program  to  process  the  data 
before  it  is  destroyed  by  another  interrupt. 

The  buffer  structure  looks  like  this: 

Buffer  Flag 
Name 

Subpicture  Tag 

Display  Program  Counter  (DPC) 

Display  Status  Register  (DSR) 

X  Status  Register  (XSR) 

Y  Status  Register  (YSR) 

The  Name  value  is  the  contents  of  the  software  Name  Register 
(described  in  N.3.5)  at  the  time  of  interrupt.  The  Tag  value  is  the 
tag  of  the  subpicture  being  displayed  at  the  time  of  interrupt.  The 
last  four  data  items  are  the  contents  of  the  display  processor  status 
registers  at  the  time  of  interrupt.  They  are  described  in  detail  in 
Table  N-l. 

Macro  Call:  .LPEN  .baddr 

where:  .baddr  is  the  address  of  the  7-word 

light  pen  status  data  buffer. 

Errors : 

None. 

If  a  .LPEN  was  already  issued  and  a  buffer  specified,  the  new  buffer 
address  replaces  the  previous  buffer  address.  Only  one  light  pen 
buffer  can  be  in  use  at  a  time. 

Example : 


.INSRT 

ilPILE 

IDISPLAY  LPILE 

.LPEN 

•  LBUF 

1  SET  UP  LPEN  BUFFER 

LOOP! 

TST 

LBUF 

ITEST  LBUF  FLAG,  WHICH 

8E0 

LOOP 

MILL  BE  SET  N0N*ZER0 

JON  LIGHT  PEN  HIT, 

1  PROCESS  OAT* 

IN  LBUF  HERE, 

CUR 

LBUF 

ICLEAR  THE  BUFFER  FL*G, 
f PERMITTING  ANOTHER  "HIT" 

BR 

LOOP 

J GO  WAIT  FOR  IT, 

N-7 


Display  File  Handler 


UBUFI  . BIKW  7  J5IVIN  WORD  IPEN  BUFFER 

UFIIEI 


Table  N-l 

Description  of  Display  Status  Words 


Bits 

Significance 

DISPLAY  PROGRAM  COUNTER  (DPC=172000) 

0-15 

Address  of  display  processor 
program  counter  at  time  of 
interrupt. 

DISPLAY  STATUS  REGI 

ISTER  (DSR-172002) 

0-1 

Line  Type 

2 

Spare 

3 

Blink 

4 

Italics 

5 

Edge  Indicator 

6 

Shift  Out 

7 

Light  Pen  Flag 

8-10 

Intensity 

11-14 

Mode 

15 

Stop  Flag 

X  STATUS  REGISTER  i 

XSRss172004) 

0-9 

X  Position 

* 

10-15 

Graphplot  Increment 

Y  STATUS  REGISTER 

(YSRs=172006) 

0-9 

Y  Position 

10-15 

Character  Register 
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The  .NAME  request  has  been  added  to  the  Version  2  Handler.  The 
contents  of  the  name  register  are  now  stacked  when  a  subpicture  call 
is  made.  When  a  light  pen  interrupt  occurs,  the  contents  of  the  name 

register  stack  may  be  recovered  if  the  user  program  has  supplied  the 

address  of  a  buffer  through  the  .NAME  request. 

The  buffer  must  have  a  size  equal  to  the  stack  depth  (default  is  10) 

plus  one  word  for  the  flag.  When  the  .NAME  request  is  entered,  the 

address  of  the  buffer  is  passed  to  the  Handler  and  the  first  word  (the 
flag  word)  is  cleared.  When  a  light  pen  hit  occurs,  the  stack's 
contents  are  transferred  and  the  flag  is  set  non— zero. 

Macro  Call:  .NAME  .baddr 

where:  .baddr  is  the  address  of  the  name  register 

buffer. 

Errors : 

None. 

If  a  .NAME  request  has  been  previously  issued,  the  new  buffer  address 
replaces  the  previous  buffer  address. 


N.2.7  .REMOV 

The  .REMOV  request  removes  the  call  to  a  user  display  file  previously 
inserted  in  the  handler's  display  file  by  the  . INSRT  request.  All 
reference  to  the  user  file  is  removed,  unlike  the  .BLANK  request, 
which  merely  bypasses  the  call  while  leaving  it  intact. 

Macro  Call:  .REMOV  .faddr 

where:  .faddr  is  the  address  of  the  display  file  to  be 

removed. 

Errors : 

No  errors  are  returned.  If  the  file  address  given  cannot  be  found, 
the  request  is  ignored. 


N.2.8  . RESTR 

The  .RESTR  request  restores  to  view  a  user  display  file  that  was 
previously  blanked  by  a  .BLANK  request.  It  removes  the  by-pass  of  the 
to  the  user  file,  so  that  the  display  processor  once  again  cycles 
through  the  user  file. 

Macro  Call:  .RESTR  .faddr 

where:  .faddr  is  the  address  of  the  user  file  that  is 

to  be  restored  to  view. 

Errors : 

No  errors  are  returned.  If  the  file  specified  cannot  be  found,  the 
request  is  ignored. 
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N.2.9  .SCROL 

This  request  is  used  to  modify  the  appearance  of  the  Display  Monitor's 
text  display.  The  .SCROL  request  permits  the  programmer  to  change  the 
maximum  line  count,  intensity  and  the  position  of  the  top  line  of  text 
of  the  scroller.  The  request  passes  the  address  of  a  two-word  buffer 
which  contains  the  parameter  specifications.  The  first  byte  is  the 
line  count,  the  second  byte  is  the  intensity,  and  the  second  word  is 
the  Y  position.  Both  line  count  and  Y  position  must  be  octal  numbers. 
The  intensity  may  be  a  number  from  1  to  8,  ranging  from  lowest  to 
highest  intensity.  If  an  intensity  of  1  is  specified,  the  scroller 
text  will  be  almost  unnoticeable  at  a  BRIGHTNESS  knob  setting  less 
than  one-half.  The  scroller  parameter  change  is  temporary,  since  an 
.UNLNK  or  CTRL  C  restores  the  previous  values. 

Macro  Call:  .SCROL  .baddr 

where:  baddr  is  the  address  of  the  two-word 

scroll  parameters  buffer. 

Errors : 


No  errors  are  returned.  No  checking  is  done  on  the  values  of  the 
parameters.  A  zero  argument  is  interpreted  to  mean  that  the  parameter 
value  is  not  to  be  changed.  A  negative  argument  causes  the  default 
parameter  value  to  be  restored. 


Example: 


SCBUFl 


SCROL 

• 

PSCBUP 

MO  JUST  SCROLL  PARAMETERS 

• 

BYTE 

5 

» DECREASE  *  LINES  TO  5, 

BYTE 

0 

I  LEAVE  INTENSITY  UNCHAN6E0 

R  0  R  0 

300 

ITOP  LINE  AT  Y  ■  300, 

N. 2.10  .START 

The  .START  request  starts  the  display  processor  if  it  was  stopped  by  a 
.STOP  directive.  If  the  display  processor  is  running,  it  is  stopped 
first,  then  restarted.  In  either  case,  the  subpicture  stack  is 
cleared  and  the  display  processor  is  started  at  the  top  of  the 
handler's  internal  display  file. 

Macro  Call:  .START 

Errors : 

None. 


N.2.11  .STAT 

The  .STAT  request  transfers  the  address  of  a  seven-word  status  buffer 
to  the  display  stop  interrupt  routine  in  VTBASE.  Once  the  transfer 
has  been  made,  display  processor  status  data  is  transferred  to  the 
buffer  by  the  display  stop  interrupt  routine  in  VTBASE  whenever  a 
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• DSTAT  or  .DHALT  instruction  is  encountered  (see  Sections  N.3.3  and 
N.3.4).  The  transfer  is  made  only  when  the  buffer  flag  is  clear 
(zero) .  After  the  transfer  is  made,  the  buffer  flag  is  set  non-zero 
and  the  .DSTAT  or  .DHALT  instruction  is  replaced  by  a  .DNOP  (Display 
NOP)  instruction. 

The  status  buffer  must  be  a  seven-word,  contiguous  block  of  memory. 
Its  contents  are  the  same  as  the  light  pen  status  buffer.  For  a 
detailed  description  of  the  buffer  and  an  explanation  of  the  status 
words,  see  section  N.2.5  and  Table  N-l. 

Macro  Call:  .STAT  .baddr 

where:  .baddr  is  the  address  of  the  status 

buffer  receiving  the  data. 

Errors : 

No  errors  are  indicated.  If  a  buffer  was  previously  set  up,  the  new 
buffer  address  is  replaced  as  the  old  buffer  address. 


N.2.12  .STOP 

The  .STOP  request  "stops"  the  display  processor.  It  actually  effects 
a  stop  by  preventing  the  DPU  from  cycling  through  any  user  display 
files.  It  is  useful  for  stopping  the  display  during  modification  of  a 
display  file,  a  risky  task  when  the  display  processor  is  running. 
However,  a  .BLANK  could  be  equally  useful  for  this  purpose,  since  the 
.BLANK  request  does  not  return  until  the  display  processor  has  been 
removed  from  the  user  display  file  being  blanked. 

Macro  Call:  .STOP 

Errors : 

None. 


NOTE 

Since  the  display  processor  must  cycle 
through  the  text  buffer  in  the  Display 
Monitor  in  order  for  console  output  to 
be  processed,  the  text  buffer  remains 
visible  after  a  .STOP  request  is 
processed,  but  all  user  files  disappear. 


N.2.13  . SYNC/ . NOSYN 

The  .SYNC  and  .NOSYN  requests  provide  program  access  to  the  power  line 
synchronization  feature  of  the  display  processor.  The  .SYNC  request 
enables  synchronization  and  the  .NOSYN  request  disables  it  (the 
default  case) . 

Synchronization  is  achieved  by  stopping  the  display  and  restarting  it 
when  the  power  line  frequency  reaches  a  trigger  point,  e.g.,  a  peak  or 
zero-crossing.  Synchronization  has  the  effect  of  fixing  the  display 
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refresh  time.  This  may  be  useful  in  some  cases  where  small  amounts  of 
material  are  displayed  but  the  amount  frequently  changes,  causing 
changes  in  intensity.  In  most  cases,  however,  using  synchronization 
increases  flicker. 

Macro  Calls:  .SYNC 
.NOSYN 

Errors : 

None. 


N. 2.14  .TRACK 

The  .TRACK  request  causes  the  tracking  object  to  appear  on  the  display 
CRT  at  the  position  specified  in  the  request.  The  tracking  object  is 
a  diamond- shaped  display  figure  which  is  light-pen  sensitive.  If  the 
light  pen  is  placed  over  the  tracking  object  and  then  moved,  the 
tracking  object  follows  the  light  pen,  trying  to  center  itself  on  the 
pen. 

The  tracking  object  first  appears  at  a  position  specified  in  a 
two-word  buffer  whose  address  was  supplied  with  the  .TRACK  request. 
As  the  tracking  object  moves  to  keep  centered  on  the  light  pen,  the 
new  center  position  is  returned  to  the  buffer.  A  new  set  of  X  and  Y 
values  is  returned  for  each  light  pen  interrupt. 

The  tracking  object  cannot  be  lost  by  moving  it  off  the  visible 
portion  of  the  display  CRT.  When  the  edge  flag  is  set,  indicating  a 
side  of  the  tracking  object  is  crossing  the  edge  of  the  display  area, 
the  tracking  object  stops  until  moved  toward  the  center.  To  remove 
the  tracking  object  from  the  screen,  repeat  the  .TRACK  request  without 
arguments . 

The  .TRACK  request  may  also  include  the  address  of  a  completion 
routine  as  the  second  argument.  If  a  .TRACK  completion  routine  is 
specified,  the  light  pen  interrupt  handler  passes  control  to  the 
completion  routine  at  interrupt  level.  The  completion  routine  is 
called  as  a  subroutine  and  the  exit  statement  must  be  an  RTS  PC.  The 
completion  routine  must  also  preserve  any  registers  it  may  use. 

Macro  Call:  .TRACK  .baddr,  .croutine 

where:  .baddr  is  the  address  of  the  two-word 

buffer  containing  the  X  and  Y 
position  for  the  track  object. 

.croutine  is  the  address  of  the  completion 
routine . 


Errors : 

None. 

Example : 

See  Section  N.10. 
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N.2.15  .UNLNK 

The  .UNLNK  request  is  used  before  exiting  from  a  program.  In  the  case 
where  the  scroller  is  present,  .UNLNK  breaks  the  link,  established  by 
. LNKRT ,  between  the  Display  File  Handler's  internal  display  file  and 
the  scroll  file  in  the  Display  Monitor.  The  display  processor  is 
started  cycling  in  the  scroll  text  buffer,  and  no  further  graphics  may 
be  done  until  the  link  is  established  again.  In  the  case  where  no 
scroller  exists,  the  display  processor  is  simply  left  stopped. 

Macro  Call:  .UNLNK 

Errors : 

No  errors  are  returned.  An  internal  link  flag  is  checked  to  determine 
if  the  link  exists.  If  it  does  not  exist,  the  request  is  ignored. 


N.3  EXTENDED  DISPLAY  INSTRUCTIONS 

The  Display  File  Handler  offers  the  assembly  language  graphics 
programmer  an  extended  display  processor  instruction  set,  implemented 
in  software  through  the  use  of  the  Load  Status  Register  A  (LSRA) 
instruction.  The  extended  instruction  set  includes:  subroutine  call, 
subroutine  return,  display  status  return,  display  halt,  and  load  name 
register. 


N.3.1  DJSR  Subroutine  Call  Instruction 

The  DJSR  instruction  (octal  code  is  173400)  simulates  a  display 
subroutine  call  instruction  by  using  the  display  stop  instruction 
(LSRA  instruction  with  interrupt  bits  set) .  The  display  stop  interrupt 
handler  interprets  the  non-zero  word  following  the  DJSR  as  the 
subroutine  return  address,  and  the  second  word  following  the  DJSR  as 
the  address  of  the  subroutine  to  be  called.  The  instruction  sequence 
is: 


DJSR  \ 

Return  address 
Subroutine  address 


Example : 


subroutine 

SQUARE : 

POINT 

^POSITION  BEAM 

100 

1  AT  (100,  100) 

100 

DJSR 

ITHEN  CALL  SUBROUTINE 

.♦« 

SQUARE 

I  TO  DRAM  A  SQUARE 

DUET 

0 

The  use  of  the  return  address  preceding  the  subroutine  address  offers 
several  advantages.  BASIC/GT  uses  the  return  address  to  branch  around 
subpicture  tag  data  stored  following  the  subpicture  address.  This 
structure  is  described  in  Section  N.5.3.  In  addition,  a  subroutine  may 
be  temporarily  bypassed  by  replacing  the  DJSR  code  with  a  DJMP 
instruction,  without  the  need  to  stop  the  display  processor  to  make 
the  by-pass. 
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The  address  of  the  return  address  is  stacked  by  the  display  stop 
interrupt  handler  on  an  internal  subpicture  stack.  The  stack  depth  is 
conditionalized  and  has  a  default  depth  of  10.  If  the  stack  bottom  is 
reached,  the  display  stop  interrupt  handler  attempts  to  protect  the 
system  by  rejecting  additional  subroutine  calls.  In  that  case,  the 
portions  of  the  display  exceeding  the  legal  stack  depth  will  not  be 
displayed. 


N.3.2  DRET  Subroutine  Return  Instruction 

The  DRET  instruction  provides  the  means  for  returning  from  a  display 
file  subroutine.  It  uses  the  same  octal  code  as  DJSR,  but  with  a 
single  argument  of  zero.  The  DRET  instruction  causes  the  display  stop 
interrupt  handler  to  pop  its  subpicture  stack  and  fetch  the  subroutine 
return  address. 

Example : 

SQUAREl  LONGV  /DRAW  A  SQUARE 

1001INTX 
0 

0 1 1  NT  X 
100 

1001INTXJMINUSX 

0 

0 1 1 NTX 
1001MJNUSX 

0KET  I  RETURN  FROM  SUBPICTURE 

0 


N.3.3  DSTAT  Display  Status  Instruction 

The  DSTAT  instruction  (octal  code  is  173420)  uses  the  LSRA  instruction 
to  produce  a  display  stop  interrupt,  causing  the  display  stop 
interrupt  handler  to  return  display  status  data  to  a  seven-word  user 
status  buffer.  The  status  buffer  must  first  have  been  set  up  with  a 
.STAT  macro  call  (if  not,  the  DSTAT  is  ignored  and  the  display  is 
resumed) .  The  first  word  of  the  buffer  is  set  non-zero  to  indicate  the 
transfer  has  taken  place,  and  the  DSTAT  is  replaced  with  a  DNOP 
(display  NOP) .  The  first  word  is  the  buffer  flag  and  the  next  six 
words  contain  name  register  contents,  current  subpicture  tag,  display 
program  counter,  display  status  register,  display  X  register,  and 
display  Y  register.  After  transfer  of  status  data,  the  display  is 
resumed. 


N.3.4  DHALT  Display  Halt  Instruction 

The  DHALT  instruction  (octal  code  is  173500)  operates  similarly  to  the 
DSTAT  instruction.  The  difference  between  the  two  instructions  is 
that  the  DHALT  instruction  leaves  the  display  processor  stopped  when 
exiting  from  the  interrupt.  A  status  data  transfer  takes  place 
provided  the  buffer  was  initialized  with  a  .STAT  call.  If  not,  the 
DHALT  is  ignored. 
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Example : 


•  STAT 

•  3BUF 

>IN1T  BUFFER 

MOV 

•ohalt.stploc 

1  INSERT  DHALT 

•  I N5RT 

PDFILE 

IDISPLAY  THE  PICTURE 

1SI 

1ST 

SBUF 

I0HALT  PROCESSED? 

B£Q 

• 

IS 

>  NO,  WAIT 

SBUFl 

,BLKW 

7 

ISTATUS  BUFFER 

OFILEI 

POINT 
.WORD 
LONG  V 

500,1350 

IP0SITI0N  NEAR  TOP  OF  12 

> DRAW  A  LINE,  MAYBE  OVER 

.W0R0 

0,400 

1  IF  IT  IS  A  12"  SCOPE, 

STPLOCI 

0N0P 

ISTATUS  WILL  BE  RETURNED 

DRET 

0 


N.3.5  DNAME  Load  Name  Register  Instruction 

The  Display  File  Handler  provides  a  name  register  capability  through 
the  use  of  the  display  stop  interrupt.  When  a  DNAME  instruction 
(octal  code  is  173520)  is  encountered,  a  display  stop  interrupt  is 
generated.  The  display  stop  handler  stores  the  argument  following  the 
DNAME  instruction  in  an  internal  software  register  called  the  "name 
register".  The  current  name  register  contents  are  returned  whenever  a 
DSTAT  or  DHALT  is  encountered,  and  more  importantly,  whenever  a  light 
pen  interrupt  occurs.  The  use  of  a  "name"  (with  a  valid  range  from  1 
to  77777)  enables  the  programmer  to  label  each  element  of  the  display 
file  with  a  unique  name,  permitting  the  easy  identification  of  the 
particular  display  element  selected  by  the  light  pen. 

The  name  register  contents  are  stacked  on  a  subpicture  call  and 
restored  on  return  from  the  subpicture. 

Example : 

The  SQUARE  subroutine  with  "named"  sides: 

SQUARE  I  DNAME 
10 

long  v 

1 00 i 1  NT  X 
0 

DNAME 
11 

0 1 1  NT  X 
100 
ONAME 
12 

1 00 1 INTX l MINUSX 
0 

ONAME 


I  NAME  IS 
110 

IDRAW  A  SIDE 


I  THIS  SIDE  IS  NAMfcO 
>11 

>  STILL  IN  LONG  VECTOR  MQOE 
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13 

01INTX 

100|MJNUSX 

ORET  | RETURN  FROM  SUbPICTURE 

0 


N.4  USING  THE  DISPLAY  FILE  HANDLER 

Graphics  programs  which  intend  to  use  the  Display  File  Handler  for 
display  processor  management  can  be  written  in  MACRO  assembly 
language.  The  display  code  portions  of  the  program  may  use  the 
mnemonics  described  in  Section  N.7.  Calls  to  the  Handler  should  have 
the  format  described  in  Section  N.6. 

The  Display  File  Handler  is  supplied  in  two  pieces,  a  library  of  MACRO 
calls  and  a  library  containing  the  Display  File  Handler  modules. 

MACRO  Library:  VTMAC . MAC 

Display  File  Handler:  VTHDLR.OBJ  (consisting  of:) 

VTBASE.OBJ 
VTCAL1 . OBJ 
VTCAL2.0BJ 
VTCAL3.0BJ 
VTCAL4.0BJ 


N.4.1  Assembling  Graphics  Programs 

To  assemble  a  graphics  program  using  the  display  processor  mnemonics 
or  the  Display  Handler  macro  calls,  the  file  VTMAC. MAC  must  be 
assembled  with  the  program,  and  must  precede  the  program  in  the 
assembler  command  string. 

Example : 

Assume  PICTUR.MAC  is  a  user  graphics  program  to  be  assembled.  An 
assembler  command  string  would  look  like  this: 

.R  MACRO 

*PICTUR=VTMAC ,PICTUR 


N.4. 2  Linking  Graphics  Programs 

Once  assembled  with  VTMAC,  the  graphics  program  must  be  linked  with 
the  Display  File  Handler,  which  is  supplied  as  a  single  concatenated 
object  module,  VTHDLR.OBJ.  The  Handler  may  optionally  be  built  as  a 
library,  following  the  directions  in  N.8.5.  The  advantage  of  using  the 
library  when  linking  is  that  the  Linker  will  select  from  the  library 
only  those  modules  actually  used.  Linking  with  VTHDLR.OBJ  results  in 
all  modules  being  included  in  the  link. 

To  link  a  user  program  called  PICTUR.OBJ  using  the  concatenated  object 
module  supplied  with  RT-11: 

.R  LINK 

*PICTUR=PICTUR, VTHDLR 
* 
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To  link  a  program  called  PICTUR.OBJ  using  the  VTLIB  library  built  by 
following  the  directions  in  N.8.5,  be  sure  to  use  the  Version  2 
Linker  s 

.R  LINK 

*PICTUR=PICTUR, VTLIB 

* 

VTLIB  (Handler  Modules) : 


Module 

CSECT 

Contains 

VTCALl 

$GTl 

.CLEAR 

.START 

.STOP 

• INSRT 

. REMOV 

VTCAL2 

$GT2 

.BLANK 

• RESTR 

VTCAL3 

$GT3 

•  LPEN 

.NAME 

.STAT 

.SYNC 

.NOSYN 

.TRACK 

VTCAL4  $GT4  .LNKRT 

.UNLNK 

.SCROL 

VTBASE  $GTB  Memory  resident  base  module 

containing  interrupt  handlers 
and  internal  display  file 

To  link  a  display  program  using  overlays,  the  modules  must  be 
specified  individually.  The  user  must  acquire  the  sources  and  follow 
the  assembly  directions  in  Section  N.8.  The  modules  VTCAL1  and  VTCAL2 
must  be  simultaneously  resident.  For  example: 

.R  LINK 

*PICTUR— PICTUR, VTBASE/C 

*VTCAL1 , VTCAL2 , VTCAL3/0 : 1/C 

*VTCAL4/0:1 

To  link  a  display  program  to  run  as  a  foreground  task: 

• R  LINK 

*PICTUR=PICTUR, VTLIB/R 


N. 5  DISPLAY  FILE  STRUCTURE 

The  Display  File  Handler  supports  a  variety  of  display  file 
structures,  takes  over  the  job  of  display  processor  management  for  the 
programmer,  and  may  be  used  for  both  assembly  language  graphics 
programming  and  for  systems  program  development.  For  example,  the 
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Handler  supports  the  tagged  subpicture  file  structure  used  by 
BASIC/GT,  as  well  as  simple  file  structures.  These  are  discussed  in 
this  section. 


N.5.1  Subroutine  Calls 

A  subroutine  call  instruction,  with  the  mnemonic  DJSR,  is  implemented 
using  the  display  stop  (DSTOP)  instruction  with  an  interrupt.  The 
display  stop  interrupt  routine  in  the  Display  File  Handler  simulates 
the  DJSR  instruction,  and  this  allows  great  flexibility  in  choosing 
the  characteristics  of  the  DJSR  instruction. 

The  DJSR  instruction  stops  the  display  processor  and  requests  an 
interrupt.  The  DJSR  instruction  may  be  followed  by  two  or  more  words, 
and  in  this  implementation  the  exact  number  may  be  varied  by  the 
programmer  at  any  time.  The  basic  subroutine  call  has  this  form: 

DJSR 

Return  Address 
Subroutine  Address 

In  practice,  simple  calls  to  subroutines  could  look  like: 

DJSR 

.WORD  .+4 

.WORD  SUB 

where  SUB  is  the  address  of  the  subroutine.  Control  will  return  to 
the  display  instruction  following  the  last  word  of  the  subroutine 
call.  This  structure  permits  a  call  to  the  subroutine  to  be  easily 
by-passed  without  stopping  the  display  processor,  by  replacing  the 
DJSR  with  a  display  jump  (DJMP)  instruction: 

DJMP 

.WORD  .+4 

.WORD  SUB 


A  more  complex  display  file  structure  is  possible  if  the  return 
address  is  generalized: 


.DJSR 

.WORD  NEXT 

.WORD  SUB 

where  NEXT  is  the  generalized  return  address.  This  is  equivalent  to 
the  sequence: 


DJSR 

.WORD  .+4 

.WORD  SUB 

DJMP 

.WORD  NEXT 


It  is  also  possible  to  store  non-graphic  data  such  as  tags  and 
pointers  in  the  subroutine  call  sequence,  such  as  is  done  in  the 
tagged  subpicture  display  file  structure  of  BASIC/GT.  This  technique 
looks  like : 
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DJSR 

.WORD  NEXT 

.WORD  SUB 

DATA 

NEXT: 


For  simple  applications  where  the  flexibility  of  the  DJSR  instruction 
described  above  is  not  needed  and  the  resultant  overhead  not  desired, 
the  Display  File  Handler  (VTBASE.MAC  and  VTCALL.MAC)  can  be 
conditionally  re-assembled  to  produce  a  simple  DJSR  call.  If  NOTAG  is 
defined  during  the  assembly,  the  Handler  will  be  configured  to  support 
this  simple  DJSR  call: 


DJSR 

.WORD  SUB 

where  SUB  is  the  address  of  the  subroutine.  Defining  NOTAG  will 
eliminate  the  subpicture  tag  capability,  and  with  it  the  tracking 
object,  which  uses  the  tag  feature  to  identify  itself  to  the  light  pen 
interrupt  handler. 


Whatever  the  DJSR  format  used,  all  subroutines  and  the  user  main  file 
must  be  terminated  with  a  subroutine  return  instruction.  This  is 
implemented  as  a  display  stop  instruction  (given  the  mnemonic  DRET) 
with  an  argument  of  zero.  A  subroutine  then  has  the  form: 

V 


SUB:  Display  Code 


DRET 
.WORD  0 


N.5.2  Main  File/Subroutine  Structure 

A  common  method  of  structuring  display  files  is  to  have  a  main  file 
which  calls  a  series  of  display  subroutines.  Each  subroutine  will 
produce  a  picture  element  and  may  be  called  many  times  to  build  up  a 
picture,  producing  economy  of  code.  If  the  following  macros  sure 
defined: 

.MACRO  CALL  <ARG> 

DJSR 

.WORD  .+4 

.WORD  ARG 

•  ENDM 

.MACRO  RETURN 

DRET 

.WORD  0 

.ENDM 

then  a  main  file/sub routine  file  structure  would  look  like: 

jMAIN  DISPLAY  FILE 

; 

MAIN :  Display  Code 

CALL  SUB1  |CALL  SUBROUTINE  1 

Display  Code 

CALL  SUB2  ;CALL  SUBROUTINE  2 

;ETC 
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/ 

/DISPLAY 

/ 

SUB1: 

; 

SUB2: 


RETURN 

SUBROUTINES 

Display  Code 
RETURN 

Display  Code 
RETURN 


/SUBROUTINE  1 

/SUBROUTINE  2 
/ETC. 


N.5.3  BASIC/GT  Subroutine  Structure 

An  example  of  another  approach  to  display  file  structure  is  the  tagged 
subpicture  structure  used  by  BASIC/GT.  The  display  file  is  divided 
into  distinguishable  elements  called  subpictures,  each  of  which  has 
its  own  unique  tag. 

The  subpicture  is  constructed  as  a  subroutine  call  followed  by  the 
subroutine.  It  is  essentially  a  merger  of  the  main  file/subroutine 
structure  into  an  in-line  sequence  of  calls  and  subroutines.  As  such, 
it  facilitates  the  construction  of  display  files  in  real  time,  one  of 
the  important  advantages  of  BASIC/GT. 

The  following  is  an  example  of  the  subpicture  structure.  Each 
subpicture  has  a  call  to  a  subroutine  with  the  return  address  set  to 
be  the  address  of  the  next  subpicture.  The  subroutine  called  may 
either  immediately  follow  the  call,  or  may  be  a  subroutine  defined  as 
part  of  a  subpicture  created  earlier  in  the  display  file.  This 
permits  a  subroutine  to  be  used  by  several  subpictures  without 
duplication  of  code.  Each  subpicture  has  a  tag  to  identify  it  and  it 
is  this  tag  which  is  returned  by  the  light  pen  interrupt  routine.  To 
facilitate  finding  subpictures  in  the  display  file,  they  are  made  into 
a  linked  list  by  inserting  a  forward  pointer  to  the  next  tag. 


SUB  1 1 

DJSR 

/START  OF  SUBPICTURE  1 

,wORD 

SUB2 

/NEXT  SUBPICTURE 

.WORD 

SUB  1*12 

IJURP  TO  THIS  SUBPICTURI 

.WORD 

l 

/TAG  *  1 

.WORD 

SUB2+6 

/POINTER  TO  NEXT  TAG 

Z  BODY 

OF  SUBPICTURE  1 

ORET 

0 

/RETURN  FROM 
/SUBPICTURE  1 

SUBS  1 

DJSR 

/START  SUBPICTURE  2 

.WORD 

SUBS 

/NEXT  SUBPICTURE 

.WORD 

SUB2+I2 

ZJUHP  TO  THIS  SUBPICTURE 

.WORD 

2 

/TAG  •  2 

.WORD 

5UB3*6 

ZPTR  TO  NEXT  TAG 

/  BODY 

OF  SUBPICTURE  2 

ORET 

/RETURN  FROM 

.WORD 

0 

/SUBPICTURE  2 
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SUB  J 1 

OJSR 

1  START  SUBPICTURE  3 

.WORD 

3UB4 

>  NEXT  SUBPICTURE 

.WORD 

SUB  1* *1? 

ICOPV  SUBPICTURE  I 
IPOR  THIS  SUBPICTURE 

.WORD 

3 

1  BUT  TAB  IT  3. 

.WORD 

3UB4*6 

1 PTR  TO  NEXT  TAG 

SU84I 

DJSR 

• 

• 

• 

1  START  SUBPICTURE  4 
IETC, 

SUMMARY  OF 

GRAPHICS 

MACRO  CALLS 

Mnemonic 


Assembly  Language 

MACRO  Call 

Expansion  (see 

Function 

(See  Note  1) 

Note  2) 

•BLANK 


•  CLEAR 

• INSRT 


•LNKRT 


Temporarily  blanks 
a  user  display  file. 

.BLANK  . f addr 

. GLOBL  $VBLNK 
.IF  NB,  . f addr 

MOV  . f addr ,  %tl00 
.ENDC 

JSR  %t07,  $VBLNK 

Initializes  handler. 

.CLEAR 

•GLOBL  $VINIT 

JSR  %t07 ,  $VINIT 

Inserts  a  call  to 
user  display  file 
in  handler's  master 
display  file. 

.INSRT  . f addr 

.GLOBL  $VNSRT 
.IF  NB,  . f addr 

MOV  .faddr,  %tOO 
.ENDC 

JSR  %t07,  $VNSRT 

Sets  up  vectors  and 
links  display  file 
handler  to  RT-11 
scroller. 

.LNKRT 

.GLOBL  $VRTLK 

JSR  %t07,  $VRTLK 

•  LPEN 


•  NAME 


•NOSYN 


•REMOV 


Sets  up  light  pen 
status  buffer. 

.LPEN  .baddr 

.GLOBL  $VLPEN 
.IF  NB,  .baddr 
MOV  .baddr,  %tOO 
.ENDC 

JSR  %t07 ,  $VLPEN 

Sets  up  buffer  to 
receive  name 
register  stack 
CONTENTS. 

.NAME  .baddr 

V 

.GLOBL  $NAME 
.IF  NB,  .baddr 
MOV  .BEDDR,  %tOO 
.ENDC 

JSR  %t07 ,  $NAME 

Disable  power  line 
sync. 

.NOSYN 

.GLOBL  $ NOSYN 

JSR  %t07,  $NOSYN 

Removes  the  call  to 
a  user  display  file. 

.REMOV  .faddr 

Vf  _  O  1 

.GLOBL  $VRMOV 
.IF  NB,  .faddr 
MOV  .faddr,  %tOO 
.ENDC 

JSR  %t07,  $VRMOV 
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.RESTR 

.SCROL 

.START 

.STAT 

.STOP 

.SYNC 

.TRACK 


.UNLNK 


Unblanks  the  user 
display  file. 


.RESTR  .faddr 


. GLOBL  $VRSTR 
IF  NB,  .faddr 
MOV  .faddr,  %tOO 
.ENDC 

JSR  %t07 ,  $VRSTR 


Adjusts  monitor 
scroller  parameters. 


.SCROL  .baddr  .GLOBL  $VSCRL 
.IF  NB,  .baddr 
MOV  .baddr,  %tOO 
.ENDC 

JSR  %t07 ,  $VSCRL 


Starts  the  display.  .START 

Sets  up  status  .STAT  .baddr 

buffer. 

Stops  the  display.  .STOP 


.GLOBL  $VSTRT 
JSR  %t07 ,  $VSTRT 


.GLOBL  $ VS TPM 
•IF  NB,  .baddr 
MOV  .baddr,  %tOO 
.ENDC 

JSR  %t07 ,  $ VS TPM 


.GLOBL  $VSTOP 
JSR  %t07 ,  $VSTOP 


Enables  power  line  .SYNC 

sync. 


.GLOBL  $SYNC 
JSR  %t07 ,  $SYNC 


Enables  the  track 
object. 


.TRACK  .baddr, 
.croutine 


.GLOBL  $VTRAK 
.IF  NB,  .baddr 
MOV  .baddr,  %tOO 
.ENDC 

.IF  NB,  .croutine 
MOV  . croutine, - 
( %  t06 ) 

.IFF 


CLR- ( %  t06 ) 
.ENDC 
.NARG  T 
.IF  EQ,  T 
CLR  %tOO 
.ENDC 
JSR  %t07 , 


$VTRAK 


Unlinks  display  .UNLNK  .GLOBL  $VUNLK 

handler  from  RT-11  JSR  %t07,  $VUNLK 

if  linked,  otherwise 
leaves  display  stopped. 


NOTE  1 


.baddr 


Address  of  data  buffer. 


. faddr 


Address  of  start  of  user 
display  file. 


.croutine 


Address  of 
routine . 


.TRACK  completion 


N-22 


Display  File  Handler 


NOTE  2 

The  lines  preceded  by  a  dot  will  not  be 
assembled.  The  code  they  enclose  may  or 
may  not  be  assembled  depending  on  the 
conditionals . 


N.7  DISPLAY  PROCESSOR  MNEMONICS 


onic 

as 

Value 

Function 

CHAR 

a 

100000 

Character  Mode 

SHORTV 

= 

104000 

Short  Vector  Mode 

LONGV 

= 

110000 

Long  Vector  Mode 

POINT 

= 

114000 

Point  Mode 

GRAPHX 

ss 

120000 

Graphplot  X  Mode 

GRAPHY 

ss 

124000 

Graphplot  Y  Mode 

RELATV 

88 

130000 

Relative  Point  Mode 

INTO 

3S 

2000 

Intensity  0 
(Dimmest) 

INTI 

a 

2200 

Intensity  1 

INT2 

a 

2400 

Intensity  2 

INT3 

* 

2600 

Intensity  3 

INT4 

a 

3000 

Intensity  4 

INT5 

a 

3200 

Intensity  5 

INT6 

a 

3400 

Intensity  6 

INT7 

a 

3600 

Intensity  7 
(Brightest) 

LPOFP 

a 

100 

Light  Pen  Off 

LPON 

88 

140 

Light  Pen  On 

BLKOFF 

a 

20 

Blink  Off 

BLKON 

88 

30 

Blink  On 

LINEO 

a 

4 

Solid  Line 

LINE1 

= 

5 

Long  Dash 

LINE2 

6 

Short  Dash 

LINE3 

a 

7 

Dot  Dash 

DJMP 

« 

160000 

Display  Jump 

DNOP 

a 

164000 

Display  No  Operation 

STATSA 

170000 

Load  Status  A 
Instruction 

LPLITE 

« 

200 

Light  Pen  Hit  On 

LPDARK 

a 

300 

Light  Pen  Hit  Off 

ITALO 

a 

40 

Italics  Off 

I  TALI 

* 

60 

Italics  On 

SYNC 

a 

4 

Halt  and  Resume  in 
Sync 

STATS B 

88 

174000 

Load  Status  B 
Instruction 
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Mnemonic 

Value 

Function 

INCR 

a 

100 

Graphplot  Increment 

(Vector/Point  Mode) 

INTX 

- 

40000 

Intensity  Vector  or 
Point 

MAXX 

a 

1777 

Maximum  X  Component 

MAXY 

* 

1377 

Maximum  Y  Component 

MINUSX 

a 

20000 

Negative  X  Component 

MINUSY 

* 

20000 

Negative  Y  Component 

(Short  Vector 

Mode) 

SHIFTX 

- 

200 

MAXSX 

a 

17600 

Maximum  X  Component 

MAXSY 

77 

Maximum  Y  Component 

MISVX 

« 

20000 

Negative  X  Component 

MISVY 

■ 

100 

Negative  Y  Component 

N.  8  ASSEMBLY  INSTRUCTIONS 


N.8.1  General  Instructions 

All  programs  can  be  assembled  in  16K,  using  RT-11  MACRO.  All 
assemblies  and  all  links  should  be  error  free.  The  following 
conventions  are  assumed: 

1.  Default  extensions  are  not  explicitly  typed.  These  are  .MAC 
for  source  files,  .OBJ  for  assembler  output,  and  .SAV  for 
Linker  output. 

2.  The  default  device  (DK)  is  used  for  all  files  in  the  example 
command  strings. 

3.  Listings  and  link  maps  are  not  generated  in  the  example 
command  strings. 


N.8.2  VTBASE 

To  assemble  VTBASE  with  RT-11  link-up  capability: 

.R  MACRO 
*VTBASE«»  VTBASE 
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N.8.3  VTCALl  -  VTCAL4 

To  assemble  the  modules  VTCALl  through  VTCAL4 * 


.R  MACRO 
*VTCAL1= VTCALl 
* VTCAL2  = VTCAL2 
•VTCAL3-VTCAL3 
*VTCAL4-VTCAL4 


N.8.4  VTHDLR 

To  create  the  concatenated  handler  modules 
.R  PIP 

* VTHDLR . 0BJ=VTCAL1 . OBJ , VTCAL2 . OB J , VTCAL3 . OB J , VTCAL4 . OB J , VTBASE . OB  J/B 


N.  8.5  Building  VTLIB.OBJ 
To  build  the  VTLIB  library* 
. R  LIBR 

* VTLIB™ VTHDLR . OBJ 


N.9  VTMAC 

.NLI3T 

I  VTMAC 

l  LIBRARY  OP  MACRO  CALLS  AND  MNEMONIC  DEFINITIONS 
I  FOR  THE  VTU  DEVICE  SUPPORT  PACKAGE 

J  DEC-U-OVTMA-B-LA 

I  COPYRIGHT  (C)  1 97 A 
I  DIGITAL  EQUIPMENT  CORPORATION 
I  MAYNARO,  MASSACHUSETTS  01754 

|  MAY  1974 

I  THE  INFORMATION  IN  THIS  DOCUMENT  IS  SUBJECT  TO 
J  CHANGE  WITHOUT  NOTICE  AND  SHOULD  NOT  BE  CONSTRUED 
I  AS  A  COMMITMENT  BY  0 1 G I  T  A  L  EQUIPMENT  CORPORATION, 

I  DEC  ASSUMES  NO  RESPONSIBILITY  FOR  ANY  ERRORS  THAT 
I  MAY  APPEAR  IN  THIS  OOCUMENT, 

I  DEC  ASSUMES  NO  RESPONSIBILITY  FOR  THE  USE 

>  OR  RELIABILITY  OF  ITS  SOFTWARE  ON  EQUIPMENT 
I  WHICH  IS  NOT  SUPPLIED  BY  DEC, 

I  THIS  SOFTWARE  IS  FURNISHED  TO  PURCHASER  UNDER  A 
I  LICENSE  FOR  USE  ON  A  SINGLE  COMPUTER  SYSTEM  AND 

>  CAN  BE  COPIED  (WITH  INCLUSION  OF  DEC'S  COPYRIGHT 

»  NOTICE)  ONLY  FOR  USE  IN  SUCH  A  SYSTEM,  EXCEPT  AS  MAY 
I  OTHERWISE  BE  PRQVIOEO  IN  WRITING  BY  DEC. 
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I  VTMAC  18  A  LIBRARY  OF  MACRO  CALLS  WHICH  PROVIDE  SUPPORT 
I  OF  THE  V T 1 1  DISPLAY  PROCESSOR,  THE  MACROS  PRODUCE  CALLS 
)  TO  THE  V T 1 1  DEVICE  SUPPORT  PACKAGE,  USING  GLOBAL  REFER- 
I  ENCES, 

I  MACRO  TO  generate  A  MACRO  with  ZERO  arguments, 

.MACRO  M  AC0  NAME, CALL 

.MACRO  NAME 

.GLOBL  CALL 

JSR  *-07, CALL 

.endm 

.ENDM 

t  MACRO  TO  GENERATE  A  MACRO  WITH  ONE  ARGUMENT 

.MACRO  MAC!  NAME, CALL 

.MACRO  NAME  ARG 

.IF  NB , ARG 

MOV  ARG, **00 

.ENDC 

.GLOBL  CALL 

JSR  X*07 , CALL 

.ENDM 

.ENDM 

»  MACRO  TO  GENERATE  A  MACRO  WITH  TWO  OPTIONAL  ARGUMENTS 

.MACRO  MAC2  NAME, CALL 

.MACRO  NAME  ARG1 , ARG2 

.GLOBL  CALL 

.IF  NB.ARGi 

MOV  ARG 1 , **00 

.ENDC 

.IF  NB.ARG2 

MOV  AHG2  » • ( X*Ofc ) 

.IFF 

CLR  • ( X*06 ) 

.NARG  T 

.IF  EQ,T 
CLR  **00 

.ENDC 
.ENDC 

JSR  X"07 , C ALL 

.ENDM 

.ENDM 
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>  macro  library  for  vtiu 


MACS 
MAC0 
MAC0 
MAC0 
MAC0 
M  AC  0 
MAC  l 

mac  i 
maci 

MAC  1 
MAC! 
MAC! 

MAC  l 
MACI 
MAC2 
MAC0 

•  MNEMONIC  DEFI 
I 

D  JMP* 1 60000 
DNOP* 164000 
DJSRM  73400 
ORET-173400 
DNAME» 1 7  3520 
DSTAT* 173420 
DHALT* 1 7  3500 
> 

CHARM  00000 

short  v  m  04000 

LONGV* l 10000 
POINT»l 14000 
GRAPHX* 120000 
GRAPHYM  24000 
PEL A  T  V ■ J  30000 
I 

INT0«2000 

INT1*2200 

INT2*2400 

INT3>2600 

INT4«3000 

INT5*3200 

INTb»3400 

INT7»3600 

» 

LPOFF* 100 
LPONM40 
0LKOFF«20 
Bu AON*  30 
L I NE0*  4 
LINE1-5 
LINE2*6 
LINE3-7 
» 


<.CLEAR>,<SVINIT» 

«.STOPM«SVSTQP> 

<.3TARTM«*VSTRT> 

<.SYNC>,«SSYNC> 

<,NOSYN>, «$NOSYN> 

<,UNLNK>, <SVUNLK> 

«.INSRT>, «$VN3RT> 

«.REMOV>,«SVRMOV> 

<,BLANK>,«SVBLNK> 

«.RESTR>,«SVR8TR> 

«,3TAT>»«SV8TPM> 

<.LPEN>,<SVIPEN> 

<tSCR0L>,<$V3CRL> 

<.NAME*,«$NAME> 

«,TRACFp*<$VTRAKp 

<.LNKRT>»<SVRTLK» 


•  INTENSITY  0 


•LIGHT  PEN  OFF 
J  LIGHT  PEN  ON 
I  BLINK  OFF 
•BLINK  ON 
ISOLID  LINE 
I  LONG  0A8H 
I  SHORT  OASH 
IOOT  OASH 


DISPLAY  PROCESSOR 


NITIONS  FOR  THE  VTU 

I  0 1  SPLAY  JUMP 
IDISPLAY  NOP 
IDISPLAY  SUBROUTINE  CALL 
IDISPLAY  SUBROUTINE  RETURN 
I  SET  NAME  REGISTER 
IRETURN  STATUS  DATA 

ISTOP  OISPLAY  AND  RETURN  STATUS  OATA 

•CHARACTER  MOOE 
•SHORT  VECTOR  MODE 
•LONG  VECTOR  MODE 
•POINT  MODE 
•GRAPH  X  MODE 
•GRAPH  Y  MODE 
•RELATIVE  VECTOR  MODE 
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STATSA*l70000 
LPL I T£»200 
LPDARK»300 
ITAU0I40 
ITAL1*60 
3YNC»4 
/ 

ST  A  TSB*  1 74000 
INCH* 1 00 
INTX*40000 
MAXX* 1777 
MAXY*  1 377 
MINUSX»20000 
MINUSY*20000 
MAXSX* 17600 
MA  XS  Ya  7  7 
MI3YX«20000 
MISVY«100 

•  LIST 


/  LOAD  STATUS  PEG  A 

i intensify  on  lpen  hit 
/DON'T  INTENSIFY 

/italics  off 
/italics  on 

/POWER  LINE  SYNC 

/LOAD  STATUS  REG  0 
I  GRAPH  PLOT  INCREMENT 
/INTENSIFY  VECTOR  OH  POINT 
/MAXIMUM  X  INCH .  •  LONG V 
/MAXIMUM  Y  I NL R ,  •  LONG V 
/NEGATIVE  X  INCREMENT 
/NEGATIVE  Y  INCREMENT 
/MAXIMUM  X  INCR,  •  SHORT V 
/MAXIMUM  Y  INCR.  -  SHORTV 
/NEGATIVE  X  INCR.  •  SHORTV 
/NEGATIVE  Y  INCH.  •  SHORTV 
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2 

3 

4 

5 

6 


/ 

;  this 
/  name 

/ 


.TITLE  EXAMPLE  HI 

EXAMPLE  USES  THE  .LPEN  STATUS  BUFFER  AnO  THE 
REGISTER  TO  MODIFY  A  DISPLAY  FILE  WITH  ThE  LIGHT  PEN, 


7 

000000 

K0SX0 

8 

000001 

*mi 

9 

000007 

PC«X7 

10 

000044 

JSW>44 

/JOS  STATUS  WQ«0 

1 1 
12 

•MCALL 

.TT1NR, .EXIT# 

.PRINT 

13 

00000 

START! 

.  LNKRT 

/LINK  TO  MONITOR 

14 

00004 

100004 

SPL 

IS 

/LINK  UP  ERROR? 

15 

00006 

.PRINT 

REMSG 

/YES.  PRINT  MESSAGE 

16 

00014 

.EXIT 

/ANO  EXIT, 

17 

00016 

If  1 

.SCROL 

WStBUF 

/ADJUST  SCROLL 

18 

00026 

.PRINT 

RMSG 

19 

00034 

. INSRT 

ROFILE 

/INSERT  DISPLAY  FILE 

20 

00044 

.LPEN 

RLSUP 

/ SET  UP  LPEN  BUFFER 

21 

00094 

092737 

SIS 

#100»##jSw 

/SET  JSW  FOR  TTINR 

21 

000100 

21 

000044 

22 

00062 

009767 

LTSTI 

TST 

LSUF 

/LIGHT  PEN  HIT? 

22 

000070 

23 

00066 

001003 

SNE 

1# 

/YES 

24 

00070 

•  TTINH 

/NO,  ANY  TT  INPUT? 

29 

00072 

103023 

see 

EXIT 

/YES,  EXIT 

2$ 

00074 

000772 

SR 

LTST 

/NO,  loop  again 

27 

00076 

016777 

If! 

MOV 

I2.P1PTR 

/RESTORE  PREVIOUS  CQI 

27 

000074 

27 

000102 

28 

00104 

016701 

MQV 

LBUF*2,R1 

/GET  NAME  VALUE 
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20 

000050 

29 

00110 

005301 

UEC 

R 1 

/subtract  One 

30 

00112 

006301 

asl 

R1 

multiply  by  T"0 

31 

00114 

060701 

ADD 

PC.R1 

/USE  TO  INDEX 

32 

00116 

062701 

ADD 

WDTABL-, Ml 

/OFF  TABLE  DT AB(. , 

32 

000062 

33 

00122 

011167 

MOV 

(Rl)flPTR 

MOVE  ADOR  INTO  IPTR 

33 

000060 

34 

00126 

016777 

MOV 

Il.PlPTR 

MODIFY  That  cooe 

34 

000042 

34 

080052 

35 

00134 

005067 

CIR 

L6UP 

/CLEAR  BUFFER  FLAG  TO 

35 

000016 

36 

tenable  another  lp  hit 

37 

00140 

000750 

BR 

LT3T 

1  LOOP  AGAIN 

38 

00142 

022700 

EXIT! 

CMP 

412. R0 

/LINE  FEED? 

38 

000012 

39 

001 4$ 

001345 

BNE 

LTST 

MO,  GET  ANOTHER 

40 

00150 

• UNLNK 

/unlink  from  monitor 

41 

00154 

.EXIT 

42 

00156 

LBUFI 

.BL*W 

7 

TLPEN  STATUS  BUFFER 

43 

00174 

103370 

11* 

.WQRO 

CHARIINT5181A0N1LP0N 

44 

00176 

103160 

12* 

.WORD 

CMAR1INT418LK0PP1LPON 

45 

00200 

000252' 

OTABLI 

.WORD 

DliD2.03 

/table  of  oisplav  FILE 

45 

00202 

000272' 

EXAMPLE  «1  RT-ll  MACRO  VM02-06  9-AUG-74  PAGE  4+ 

45  00204  000412' 


46 

ILOCATIONS  TO  BE  MODIFIED 

47 

00206 

000252' IPTRI 

.WORD 

01 

/PREVIOUS  LOCATION  MODIFIED 

48 

00210 

000002 

SCBuFl 

.WORO 

2 

/SCROLL  LINE  COUNT 

49 

00212 

001000 

.WORD 

1000 

/SCROLL  TOP  V  POS. 

50 

00214 

041 

emsg* 

.ASCI2 

/ 1  ERROR  1  / 

/ERROR  MESSAGE 

50 

00215 

105 

50 

00216 

122 

50 

00217 

122 

50 

00220 

117 

50 

00221 

122 

50 

00222 

041 

58 

00223 

000 

51 

.EVEN 

52 

00224 

105 

MSG  | 

. ASCIZ 

/EXAMPLE  #1/ 

/I.D.  MESSAGE 

52 

00225 

130 

52 

00226 

101 

52 

00227 

115 

52 

00230 

120 

52 

00231 

114 

52 

00232 

105 

52 

00233 

040 

52 

00234 

043 

52 

00235 

061 

52 

00236 

000 

S3 

.EVEN 

54 

/ 

55 

/  UISPLAY  FILE 

FOR  EXAMPLE  #1 

56 

> 

57 

00240 

114000 

OFlLEl 

POINT 

58 

00242 

000100 

100 

59 

00244 

000500 

500 

60 

00246 

173520 

UNAME 

61 

00280 

000001 

1 

62 

00262 

103160 

Di» 

CNA*  1BUKQFF1  XNT41LP0N 
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63  00254 

117 

.ASCII  /ONE./ 

63  00255 

116 

63  00256 

105 

63  00257 

066 

64  00260 

114000 

POINT 

65  00262 

000100 

100 

66  00264 

000300 

300 

67  00266 

173520 

ONAME 

68  00270 

000002 

2 

69  00272 

103160 

021 

C.MAR1BLK0FFHNT41LP0N 

70  00274 

124 

.ASCII  /TWO./ 

70  00275 

127 

70  00276 

117 

70  00277 

056 

71  00300 

114000 

POINT 

72  00302 

000100 

100 

73  00304 

000100 

100 

74  00306 

173520 

ONAME 

75  00310 

000003 

3 

76  00312 

103160 

031 

CHAR1BLK0FP  J1NT41LP0N 

77  00314 

124 

.ASCII  /THREE,/ 

77  00315 

110 

EXAMPLE  *1 

RT-ll 

MACRO  VM02-06  9-AUG-74 

77  00316 

122 

77  00317 

105 

77  00320 

105 

77  00321 

056 

78  00322 

173300 

DRET 

79  00324 

000000 

0 

80 

000000 ' 

.END  START 

EXAMPLE  01 

RT-11 

MACRO  VM02-06  9-AUG-74 
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SYMBOL  T ABLE 


blkqfp* 

000020 

BLKQN 

9 

000030 

CHAR 

■ 

100000 

DFlLfc 

000240R 

uhalt 

« 

173500 

DJMP 

■ 

160000 

0J5R  « 

173400 

ONAME 

9 

173520 

ONOP 

« 

164000 

dret  * 

173400 

OSTAT 

* 

173420 

DTABL 

000200R 

01 

000252R 

02 

0002/2R 

03 

000312R 

EMSG 

000214R 

EXIT 

000142R 

GRAPHX* 

120000 

GRAPMY* 

124000 

iNCR 

000100 

INTX 

■ 

040000 

INT0  • 

002000 

INTI 

002200 

INT2 

* 

002400 

INT3  ■ 

002600 

INT4 

003000 

INT5 

■ 

003200 

INTe  • 

003400 

I NT7 

003600 

IPTR 

000206R 

ITAL0  • 

000040 

ITALI 

000060 

11 

000 1 7  4R 

12 

000176R 

JSN 

000044 

LBUF 

000156R 

line*  • 

000004 

CINE1 

000005 

LINE2 

■ 

000006 

LINE3  • 

000007 

LONG  V 

110000 

LPOARK* 

000300 

LPUITE4 

000200 

LPOFF 

000100 

LPON 

9 

000140 

LTST 

000062R 

MAXSX 

017600 

MAXSY 

6 

000077 

MAXX  » 

001777 

MAXY 

001377 

MINUSX* 

020000 

MINUbY* 

020000 

MISVX 

020000 

MIS  YY 

■ 

000100 

MSG 

000224R 

PC 

■X000007 

POINT 

6 

114000 

RELATV" 

130000 

R0 

■X000000 

R1 

■X00000 1 

SCBUP 

000210R 

SHORTY 

104000 

START 

000000K 

STATSA« 

170000 

bTATSB 

174000 

SYNC 

■ 

000004 

$VLPEN» 

******  G 

iVNSRT 

******  G 

$  VRTLK  * 

****** 

SVSCRL« 

******  G 

svunlk 

******  G 

,  ASS,  000000  00(9 

000326  001 

ERRORS  DtTEcTfcOl  0 
FREE  CORtl  i t> i  1 7 •  WOROb 


manexi,lp»*vtmac,manexi 
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2 

3 

4 

5 

6 
7 


.TITLE  EXAMPLE  #2 
Z 

I  THIS  EXAMPLE  USES  THE  TRACKING  OBJECT  AND  THE  TRACK 

i  completion  routine  to  Cause  a  vector  to  follow 

Z  THE  LICMT  PEN  FROM  A  SET  POINT  AT  (300,500). 

Z 


a 

000000 

R0*X0 

9 

000001 

*l«t 

10 

000006 

SP*X6 

11 

000007 

PC*X7 

12 

. MC ALL 

.EXIT, .TTYIN, 

.PRINT 

13 

00000 

STARTI 

•LNKRT 

ILINK  TO  MONITOR 

14 

00004 

100004 

BPL 

IS 

ILlNK  UP  ERROR? 

15 

00006 

.PRINT 

*EMSG 

1  YES ,  INFORM  USER 

16 

00014 

.EXIT 

/AND  EXIT 

17 

00016 

1st 

.  INSRT 

PDPILE 

/  INSERT  DISPLAY  FILE 

18 

00026 

.TRACK 

#TBUF,*TCOM 

IOIsPlAY  TRACK  object 

19 

00042 

004767 

JSR 

PC, WAIT 

> WAIT  FOR  <CR> 

19 

000006 

20 

00046 

.UNLNK 

/UNLINK  FROM  mOnITOR 

21 

00052 

.EXIT 

22 

00054 

WAIT! 

•  TTYIN 

/GET  CHAR,  FROM  TTY 

23 

00060 

022700 

CMP 

*12, KB 

/LINE  KEtO? 

23 

000012 

24 

00064 

001373 

BNE 

WAIT 

/NO,  GET  ANOTHER 

23 

00066 

000207 

RTS 

PC 

26 

000/0 

000600 

TBUFI 

.WORD 

500,500 

ZTNALK  BUFFER  InITED  TO 

26 

00072 

000500 

27 

/START  TRACK  AT  (600,500! 

28 

I 

29 

I  TRACK 

COMPLETION  ROUTINE  ENTERED  AT  INTERRUPT  LEVEL 

30 

/  FROM 

DISPLAY 

FILE  HANDLER  WITH  QISPLAY  STOPPED. 

31 

Z  USED 

TU  UPDATt  DISPLAY  FILE 

with  data  from  TbuF, 

32 

Z 

33 

000/4 

010146 

TCUMI 

MOV 

R 1 , • (SP) 

/SAVE  Rl 

34 

00076 

016701 

MOV 

TBUF , R 1 

/NEW  X 

34 

177766 

35 

00102 

166701 

SUB 

0  X  ,  R  1 

/NEw  X  -  OLD  X 

33 

000052 

36 

00106 

100003 

BPL 

IS 

/POSITIVE  DIFFERENCE? 

37 

00110 

005401 

NEG 

Rl 

/NO,  SO  MAKE  POSITIVE 

38 

00112 

052701 

BIS 

#MINUSX,Ri 

/BUT  SET  MINUS  BIT 

38 

020000 

39 

00116 

052701 

1  *  * 

BIS 

#INTX,R1 

/also  set  intensify  bit 

39 

040000 

40 

00122 

010167 

MOV 

Rl ,  OX 

/then  store  in  dfile. 

40 

000040 

41 

00126 

016701 

MOV 

TBUF*2 , R 1 

/NEW  Y 

41 

177740 

42 

00132 

166701 

SUB 

0  Y ,  R  l 

/NEW  Y  -  OLD  Y 

42 

000024 

43 

00136 

100003 

BPL 

2S 

/POSITIVE  DIFFERENCE? 

44 

00140 

005401 

NEG 

Rl 

/ NO , Su  MAKE  POSITIVE 

45 

00142 

052701 

BIS 

#MINUSX,R1 

/and  set  MINUS  bit 

45 

020000 

46 

00146 

010167 

2S 1 

MOV 

R 1 , 0  Y 

/then  store  in  dfile 
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47  00192 

48  00194 

49 

50 

51 

52  00196 
59  00160 

54  00162 

55  00164 

56  00166 

57  00170 

58  00172 

59  00174 

60  00176 
60  00177 
60  00200 
60  00201 
60  00202 
60  00209 
60  00204 
60  00205 
60  00206 


012601 

000207 


114000 
000900 
000900 
119000 
000000 
000000 
179400 
000000 
129 
1 1 7 
122 
122 
191 
054 
040 
124 
110 


MOV 

RTS 


(SP)+,R1 

PC 


DISPLAY  FILE  FOR  EXAMPLE  #2 


I 
I 
I 

DFILEI 
OX  t 
OYI 

OX  1 
OY 1 


EMSGI 


POINT 

500 

500 

LQNGV 1 INT4 


» WORD 
.WORD 
URET 
0 

. ASCIZ 


0 

0 


/SORRY,  There 


60  00207  105 
60  00210  122 
60  00211  105 
60  00212  040 
60  00219  129 
60  00214  1  ca 3 
60  00219  109 
60  00216  119 
60  00217  129 
60  00220  040 
60  00221  124 
60  00222  1 1 7 


60  00220  040 
60  00224  102 
60  00229  105 
60  00226  040 
60  00227  101 
60  00290  040 
60  00291  120 
60  00292  122 
60  00299  1 1 7 
60  00294  102 
60  00295  114 
60  0029ft  105 


60  00297  1 1 D 

60  00240  000 

61  .EVEN 

62  000000'  .ENQ  START 


I  RESTORE  R 1 

#  EX  I T  FROM  COMPLETION  ROUTINE 


I  SET  POINT  AT 

I  (500,500) 

>  DR  AW  A  VECTOR 
I  INITIALLY  NOWHERE 

J DISPLAY  FILE  EnO 

SEEMS  TO  BE  A  PROBLEM/ 
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SYMBOL  TABLE 


BLKOPF* 

000020 

BLKON  • 

000030 

CHAR 

« 

100000 

dfile 

000156R 

ohalt  • 

173500 

0  JMP 

■ 

160000 

OJSR  * 

173400 

ONAME  • 

173520 

DNOP 

V 

164000 

ORCT  • 

173400 

DSTAT  * 

173420 

DX 

000166R 

OY 

000170R 

EMSG 

0001 7  6R 

GRAPHX* 

120000 

grapmy» 

124000 

1NCR  * 

000100 

I  NT  X 

* 

040000 

INTa  • 

002000 

INTI  i 

002200 

INT2 

* 

002400 

INT3  » 

002600 

INTA  • 

003000 

INT5 

p 

003200 

INTg  « 

003400 

INT7  * 

003600 

ITAL0 

p 

000040 

itali  • 

000060 

LINE0  • 

000004 

LINE  1 

* 

000005 

LINE2  • 

000006 

LINE3  * 

000007 

LONGV 

p 

110000 

LPOARKt 

000300 

LPLITE* 

000200 

lpoff 

p 

000100 

LPON  ■ 

000140 

maxsx  ■ 

017600 

MAXSY 

p 

000077 

MAXX  • 

001777 

maxy  * 

001377 

M I NUSX  * 

020000 

MINUSYl 

020000 

MISVX  * 

020000 

MISVY 

p 

000100 

OX 

000160R 

OY 

000162R 

PC 

■X000007 

POINT  • 

114000 

«ELATV* 

130000 

R0 

**000000 

R 1  **000001 

SHORTY* 

104000 

SP 

■X000006 

START 

000000R 

STATSA* 

170000 

STATS0* 

174000 

SYNC  • 

000004 

TBUF 

000070R 

T  COM 

000074R 

WAIT 

000094R 

SYNSRT* 

******  Q 

SVRTLK* 

******  a 

SVTRAM* 

******  £ 

SYUNLA* 

******  G 

•  AS®  • 

000000 

000 

000242  001 

ERRORS  oETECTEOI  0 
FREE  CORE 1  1»022,  WORDS 

MANE*2iLPl*VTMACtMANEX2 
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This  appendix  is  reserved  for  the  RT-11 
BATCH  documentation,  which  will  be  avail¬ 
able  at  a  later  date. 
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ERROR  MESSAGE  SUMMARY 

This  appendix  summarizes  in  alphabetical  order  all  error  messages 
which  may  occur  under  the  RT-11  System.  The  appropriate  program  for 
reference  is  included  for  the  user's  convenience.  Error  types  are 
grouped  into  the  following  categories: 


ACTION 

Error  message  is  sent  to  the  terminal  and 
execution  stops.  A  user-response  is  expected 
before  execution  can  continue. 

COUNT :n  Error  message  is  sent  to  the  terminal;  execution 


continues  until  nth  occurrence  of  error,  at  which 
time  the  error  is  treated  as  FATAL.  (For  FORTRAN 
messages  only.) 

FATAL 

Error  message  is  sent  to  the  terminal  or  the 
listing  output  file;  the  current  command  or 
statement  is  ignored #  or  execution  is  terminated , 
in  which  case  the  user  must  enter  another  command. 

IGNORE 

A  subcategory  of  INFORMational ,  which  is  used  for 
FORTRAN  messages  only.  Error  is  detected  but  no 
message  is  sent  to  the  terminal  or  the  listing 
output  file,  and  execution  continues. 

INFORM 

Informational  message;  an  error  condition  is 
detected  and  the  user  is  informed,  either  at  the 
terminal  or  in  the  listing  file;  execution 
continues.  The  error  condition  may  affect 
execution  at  a  later  time,  and  may  require  future 
action. 

WARNING 

A  subcategory  of  INFORMational;  error  message  is 
sent  to  the  terminal  or  the  listing  output  file, 
and  execution  continues  totally. 

Error  Message  Summary 


ERROR 

MESSAGE  PROGRAM  TYPE  MEANING 


A  MACRO  INFORM 

Addressing  error.  An  address 
within  the  instruction  was 
incorrect.  Also  may  indicate 
a  relocation  error.  The 
addition  of  two  relocatable 
symbols  is  flagged  as  an  A 
error.  May  also  indicate 
that  a  local  symbol  was 
defined  more  than  128  words 
from  the  beginning  of  a  local 
symbol  block. 

ADDITIVE  REF  OF  xxxxxx 
at  segment  yyyyyy 

LINKER  WARNING 

Rule  1  of  overlay  rules 
explained  in  Section  6.6  has 
been  violated.  xxxxxx 
represents  the  entry  point; 
yyyyyy  represents  the  segment 
number. 

?ADDR?  MONITOR  FATAL 

Address  out  of  range  in  E  or 
D  command. 

7ADDR  NOT  IN  SEG?  PATCH  FATAL 

The  address  was  not  in  the 
specified  segment. 

ADJUSTABLE  DIMENSIONS  ILLEGAL  FOR  ARRAY 

FORTRAN  WARNING 

**** 

Adjustable  arrays  must  be  a 
dummy  argument  in  a 
subprogram ,  and  the 
adjustable  dimensions  must  be 
integer  dummy  arguments  in 
the  subprogram.  Violation  of 
this  rule  causes  a  dimension 
of  1  to  be  used. 

FORTRAN  INFORM 

All  arrays  must  be 
dimensioned  with  integer 
constants  except  as  specified 
in  the  RT-11  FORTRAN  COMPILER 
AND  OBJECT  TIME  SYSTEM  USERfS 
MANUAL  ( DEC- 1 1-LRFP A- A- D ) . 

?ARG  ARGUMENT  ERROR  AT  LINE  xxxxx 

BASIC  FATAL 

Arguments  in  a  function  call 
do  not  match  (in  number  or  in 
type)  the  argument  defined 
for  the  function. 

ARRAY  ****  HAS  TOO  MANY  DIMENSIONS 

FORTRAN  INFORM 

An  array  can  have  up  to  seven 
dimensions. 

?ATL  ARRAYS  TOO  LARGE  AT  LINE  xxxxx 

BASIC  FATAL 

There  was  not  enough  room  in 
the  memory  available  for  the 
arrays  specified  in  the  DIM 
statements. 
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ATTEMPT  TO  EXTEND  COMMON  BACKWARDS 


FORTRAN 

INFORM 

While  attempting  to 
equivalence  arrays  in  COMMON  9 
an  attempt  was  made  to  extend 
COMMON  past  the  recognized 
beginning  of  COMMON  storage. 

B 

MACRO 

INFORM 

Bounding  error.  Instructions 
or  word  data  would  be 
assembled  at  an  odd  address 
in  memory.  The  location 
counter  is  updated  by  +1. 

******  Q 

FORTRAN 

INFORM 

Columns  1-5  of  a  continuation 
line  were  not  blank. 
(Columns  1-5  of  a 
continuation  line  must  be 
blank  except  for  a  possible 

1 D1  in  column  1);  the  columns 
are  ignored  and  compilation 
continues. 

?/B  NO  VALUE? 

LINKER 

FATAL 

The  /B  switch  requires  an 
octal  number  as  an  argument. 

?/B  ODD  VALUE? 

LINKER 

FATAL 

The  argument  to  the  /B  switch 
was  not  an  unsigned  even 
octal  number. 

?BAD  CHECKSUM? 

PATCHO 

FATAL 

A  formatted  binary  block  in 
the  input  file  had  a  checksum 
which  did  not  agree  with  that 
calculated  for  its  contents. 

?BAD  GSD? 

"V 

LINKER 

FATAL 

There  was  an  error  in  the 
global  symbol  directory. 
(GSD) .  The  file  is  probably 
not  a  legal  object  module. 
This  error  message  occurs  on 
pass  1  of  the  Linker. 

?BAD  LIBR? 

LIBR 

FATAL 

The  user  attempted  to  build  a 
library  file  containing  no 
directory  entries  or  gave  an 
illegally  constructed  library 
file  to  the  Librarian  as 
input. 

BAD  MACRO  ARG 

EXPAND 

INFORM 

The  macro  argument  was  not 
formatted  correctly. 

?BAD  OBJ? 

LIBR 

FATAL 

A  bad  object  module  was 

detected  during  input. 

PATCHO 

FATAL 

The  input  file  contained 
information  which  could  be 
interpreted  as  an  object 
module . 
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bad  overlay  at  seg  #yyyyyy 

LINKER  WARNING 


Overlay  tried  to  store  text 
outside  of  its  region;  check 
for  an  .ASECT  in  overlay, 
yyyyyy  represents  the  segment 
number. 


?BAD  PATCH? 


?BAD  PPN? 


?BAD  RLD? 


?BAD  SWITCH? 


PATCHO  INFORM 


FILEX  FATAL 


LINKER  FATAL 


EXPAND  FATAL 

LINKER  FATAL 


Checksum  entered  on  exit  does 
not  agree  with  that 
calculated  by  PATCHO  but  the 
patch  was  made  as  specified. 
This  probably  indicates  a 
typing  error. 

The  DOS/BATCH  user 
identification  code  was  not 
in  the  form  [nnn,nnn] ,  where 
each  nnn  is  an  octal  number 
less  than  or  equal  to  377 
(octal) . 

There  was  an  invalid 
relocation  directory  (RLD) 
command  in  the  input  file; 
the  file  is  probably  not  a 
legal  object  module.  The 
message  occurs  on  pass  2  of 
the  Linker. 

An  unrecognized  command 
string  switch  was  specified. 

LINK  did  not  recognize  a 
switch  specified  on  the  first 
command  line.  On  a 
subsequent  command  line,  a 
bad  switch  causes  this 
warning  message  but  does  not 
restart  the  Linker. 


MACRO  FATAL 

PATCH  FATAL 

?BAD  x  SWITCH  IGNORED? 

LINKER  WARNING 


The  switch  specified  was  not 
recognized  by  the  program. 

Typed  a  switch  other  them  /O 
or  /M. 

LINK  did  not  recognize  a 
switch  (x)  specified  in  the 
command  line.  The  switch  is 
ignored  and  linking 

continues . 


?BDR  BAD  DATA  READ  AT  LINE  xxxxx 

BASIC  FATAL 


BExxxxxx 


ODT  FATAL 


P-4 


Item  input  from  data  segment 
list  by  READ  statement  was 
bad. 

Bad  breakpoint  entry  from 
location  xxxxxx.  Breakpoint 
routine  was  entered  for  no 
known  breakpoint;  illegal 
trace  trap  instruction;  T-bit 
was  set  in  status  register. 


Error  Message  Summary 


or  a  jump  to  the  middle  of 
ODT  occurred. 

7B00T  COPY?  PIP  FATAL 

An  error  occurred  during  an 
attempt  to  write  bootstrap 
with  /U  switch. 

7B0TT0M  ADDR  WRONG?  PATCH  FATAL 

The  bottom  address  specified 
or  contained  in  location  42 
of  an  overlay  file  was 
incorrect.  Specify  the 
correct  one  using  the  bsB 
command. 

BRT  BAD  DATA- RETYPE  FROM  ERROR 

BASIC  ACTION 

Item  entered  to  input 

statement  was  bad. 

?BSO  BUFFER  STORAGE  OVERFLOW  at  line  xxxxx 

BASIC  FATAL  Not  enough  room  available  in 


file  buffers. 

?BSW?  ASEMBL  FATAL 

The  switch  specified  was  not 
recognized  by  the  program. 

BYTE  RELOCATION  ERROR  AT  XXXXXX 

LINKER  WARNING 

Linker  attempted  to  relocate 
and  link  byte  quantities,  but 
failed.  xxxxxx  represents 
the  address  at  which  the 
error  occurred.  Failure  is 
defined  as  the  high  byte  of 
the  relocated  value  (or  the 
linked  value)  not  being  all 
zero.  In  such  a  case,  the 
value  is  truncated  to  8  bits 
and  the  Linker  continues 
processing  (for  save  image 
and  LDA  files  only;  byte 
relocation  is  completely 
illegal  for  REL  files) . 

C  FORTRAN  FATAL 

Constant  subscript  overflow. 
Too  many  subscripts  have  been 
employed  in  a  statement. 

SOLUTION  -  Simplify  the 
statement. 

******  c  FORTRAN  INFORM 

Illegal  continuation. 
Comments  cannot  be  continued 
and  the  first  line  of  a 
program  unit  cannot  be  a 
continuation  line.  The 
continued  comment  is  ignored 
and  compilation  continues. 

7C-CHAIN-ONLY-CUSP?  CREF  FATAL 

An  attempt  was  made  to  either 
MR  CREF"  or  to  "START"  a  copy 
of  CREF  which  was  in  memory 
due  to  a  previous  MACRO  run 
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which  had  chained  to  CREF  but 
was  aborted  from  the  console 
terminal  (via  CTRL  C) .  CREF 
can  only  be  "chained"  to;  it 
cannot  be  invoked  without 
MACRO. 

?C-CRF  FILE  ERROR?  CREF  FATAL 

An  output  error  occurred 
while  accessing 
" DK : CREF • TMP " ,  the  temporary 
file  passed  from  MACRO  to 
CREF. 

?C- DEVICE?  CREF  FATAL 

An  invalid  device  was 
specified  to  CREF  by  MACRO 
(system  error) • 

?C-LST  FILE  ERROR?  CREF  FATAL 

An  input/output  error 
occurred  while  attempting  to 
write  the  cross-reference 
table  to  the  listing  file. 

*CB  ALMOST  FULL*  EDIT  ACTION 

The  command  currently  being 
entered  is  within  10 
characters  of  exceeding  the 
space  available  in  the 
Command  Buffer. 

?CB  FULL?  EDIT  INFORM 

Command  exceeded  the  space 
allowed  for  a  command  string 
in  the  Command  Buffer.  The 
last  10  characters  entered 
are  ignored. 

?CHK  SUM?  PIP  INFORM 

A  checksum  error  occurred  in 
a  formatted  binary  transfer. 

COMMON  BLOCK  EXCEEDS  MAXIMUM  SIZE 

FORTRAN  INFORM 

An  attempt  was  made  to 
allocate  more  space  to  COMMON 
than  is  physically 
addressable  (>32K  words). 

?COR  OVR?  FILEX  FATAL 

There  was  insufficient  main 
storage  for  buffers  and  input 
list  expansion.  Try  copying 
files  one  at  a  time,  without 
using  the  "wild-card"  (*•*) 
construction  on  input. 

PIP  FATAL 

Memory  overflow — too  many 
devices  and/or  file 
specifications  (usually  *•* 
operations)  and  no  room  for 
buffers. 

SRCCOM  FATAL 

Not  enough  memory  to  hold  a 
particular  difference 
section. 
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?CORE? 

ASEMBL 

FATAL 

There  were  too  many  symbols 
in  the  program  being 
assembled.  Try  dividing 
program  into  separately- 
assembled  subprograms. 

LINKER 

FATAL 

There  was  not  enough  memory 
to  accommodate  the  command  or 
the  resultant  load  module. 

7CSECT  ERROR? 

LIBR 

FATAL 

The  user  has  extended  beyond 

the  allowable  .CSECT  space 
for  an  object  module  to  be 
placed  in  the  library  (i.e., 
the  object  module  contains 
greater  than  127 (decimal) 
.CSECTs) . 

CTn:  PUSH 

REWIND 

OR  MOUNT  NEW 

VOLUME 

PIP 

ACTION 

A  new  cassette  must  be 

mounted  on  drive  n  to  allow 

continuation  of  an  I/O 
operation.  The  operation  is 
continued  automatically  as 
soon  as  the  new  cassette  is 
mounted. 

D 

MACRO 

INFORM 

Doubly-de fined  symbol 

referenced.  Reference  was 

made  to  a  symbol  which  was 
defined  more  than  once. 

DANGLING  OPERATOR  FORTRAN 

INFORM 

An  operator  (+,  -,  *,  /, 

etc.)  was  missing  an  operand. 
Example:  (I«*J+) . 

?DAT? 

MONITOR 

FATAL 

The  DATE  command  argument  was 
illegal,  or  no  argument  was 
given  and  the  date  has  not 
yet  been  set. 

?DCE  DEVICE  CHANNEL  ERROR  AT 

LINE  xxxxx 

BASIC 

FATAL 

The  device  channel  number 

specified  for  a  sequential  or 
virtual  memory  file  was  out 
of  range  (1-7) ,  or  an  attempt 
was  made  to  open  a  virtual 
memory  file  on  a  non-file 
structured  device. 

DEFECTIVE 

DOTTED 

KEYWORD 

FORTRAN 

INFORM 

A  dotted  relational  operator 
was  not  recognized.  Also, 
possible  misuse  of  decimal 
point. 

?DEV  FUL? 

CSI 

FATAL 

Output  file  did  not  fit. 

PIP 

FATAL 

No  room  on  device  for  file. 
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?DEV  FULL? 


?DIR  ERR? 


FILEX 

FATAL 

There  was  no  room  in  the 
directory  for  the  filename  or 
there  was  no  room  on  the 
output  device  for  the  file 
(in  which  case  the  filename 
is  not  placed  in  the  output 
device  directory) . 

LIBR 

FATAL 

The  device  was  full;  LIBR 
was  unable  to  create  or 
update  the  indicated  library 
file.  The  CSI  prints  an 
asterisk  and  waits  for  the 
user  to  enter  another  command 
line. 

FILEX 

FATAL 

An  error  occurred  while 
reading  or  looking  up  the 
directory  of  the  input 

device,  or  the  input  device 
does  not  have  the  proper  file 
structure. 


?*DIR  FULL*? 


EDIT 

FATAL 

No  room  in 

device  directory 

for  output 

file. 

?DNR  DEVICE  NOT  READY 

BASIC  FATAL 


An  OLD  command  reads  a  file 
which  did  not  have  any  BASIC 
statements . 


DO  TERMINATOR  ***  PRECEDES  DO  STATEMENT 

FORTRAN  INFORM  The  statement  specified  as 

the  terminator  of  a  DO  loop 
must  come  after  the  DO 
statement. 


7DUMP  ERROR?  PATCHO  FATAL 

?DV0  DIVISION  BY  0  AT  LINE  xxxxx 

BASIC  FATAL 

E  MACRO  INFORM 

******  E  FORTRAN  INFORM 


An  input/output  error 
occurred  while  dumping  a 
module . 


Program  attempted  to  divide 
some  quantity  by  0. 

End  directive  not  found.  (A 
.END  is  generated.) 

Missing  END  statement.  An 
END  statement  is  supplied  by 
the  Compiler  if  end-of-file 
is  encountered. 


?***  ERROR  ***  text 

EXPAND  Indicates  nonfatal  errors  in 

the  input  file;  "text"  is  a 
short  explanation  of  the 
error;  refer  to  individual 
text  listing. 
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?*EOF*? 

EDIT 

FATAL 

Attempted  a  Read,  Next  or 
file  searching  command  and  no 
data  was  available. 

tER  + ERROR  AT  LINE  XXXXX 

BASIC 

FATAL 

The  program  tried  to  compute 
the  value  AtB ,  where  A<0  and 
B  was  not  an  integer.  This 
produces  a  complex  number 
which  is  not  represented  in 
BASIC.  x>87  in  EXP(x) 
function. 

?ER  RD  DIR? 

PIP 

FATAL 

Unrecoverable  error  reading 
directory.  Check  volume  for 
off-line  or  write-locked 
condition  and  try  operation 
again. 

?ER  RD  OVLY? 

MONITOR 

FATAL 

An  I/O  error  occurred  while 
reading  a  KMON  overlay  to 
process  the  current  command. 
This  is  a  serious  error, 
indicating  that  the  system 
file  MONITR.SYS  is 
unreadable. 

PER  WR  DIR? 

PIP 

FATAL 

Unrecoverable  error  writing 
directory.  Try  again. 

?"<  >"ERR? 

EDIT 

FATAL 

Iteration  brackets  were 
nested  too  deeply  or  used 
illegally  or  brackets  were 
not  matched. 

?ERR  nn  text 

FORTRAN 

Error  diagnostics  detected  by 
the  Object  Time  System  are 
reported  in  either  short  form 
where  nn  is  a  decimal  error 
condition,  or  long  form  where 
"text"  is  an  added  short 
error  description.  Refer  to 
individual  decimal  error. 

7ERR0R  ERROR? 

LINKER 

FATAL 

An  error  occurred  while  the 
Linker  was  in  the  process  of 
recovering  from  a  previous 
system  or  user  error. 

7ERROR  IN  FETCH? 

LINKER 

FATAL 

The  device  is  not  available. 

?ETC  EXPRESSION 

TOO  COMPLEX 
BASIC 

AT  LINE 
FATAL 

XXXXX 

The  expression  being 

evaluated  caused  the  stack  to 
overflow  (usually  because  the 
parentheses  were  nested  too 
deeply) •  The  degree  of 
complexity  that  produces  this 
error  varies  according  to  the 
amount  of  space  available  in 
the  stack  at  the  time. 
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Breaking  the  statement  into 
several  simpler  ones 
eliminates  the  error. 

EXPECTING  LEFT  PARENTHESES  AFTER  **** 

FORTRAN  INFORM 

An  array  name  or  function 
name  reference  was  not 
followed  by  a  left 
parenthesis. 

?EXT  NEG?  PIP  FATAL 

A  /T  command  attempted  to 
make  file  smaller. 

EXTRA  CHARACTER  AT  END  OF  STATEMENT 

FORTRAN  INFORM 

All  the  necessary  information 
for  a  syntactically  correct 
FORTRAN  statement  has  been 
found  on  this  line,  but  more 
information  exists.  Possibly 
due  to  inadvertent 
continuation  signal  on  next 
line,  or  a  missing  comma. 

F?  MONITOR  FATAL 

A  CTRL  F  was  typed  and  no 
foreground  job  exists. 

FATAL  ERROR  n  FORTRAN 

Diagnostics  in  this  format 
report  hardware  error 
conditions  and  conditions 
which  may  require  rewriting 
the  program,  n  is  a  single 
letter  representing  an  error 
code;  refer  to  the 
individual  listing  of  n. 

?F  ACTIVE?  MONITOR  FATAL 

Neither  FRUN  nor  UNLOAD  may 
be  used  when  a  foreground  job 
already  exists  and  is  active. 

?FDE  FILE  DATA  ERROR  AT  LINE  xxxxx 

BASIC  FATAL 

Tried  to  write  an  element  on 
an  integer  virtual  memory 
file  outside  the  range 
(x) <32,768. 

7FEATURE  NOT  IMP?  FILEX  FATAL 

An  operation  was  attempted 
which  FILEX  cannot  perform 
(e.g.,  zeroing  an  RT-11 
device) . 

?FG  ACTIVE?  FILEX  FATAL 

An  attempt  was  made  to  use  /T 
when  a  foreground  job  was 
active.  The  transfer  is  not 
allowed  until  the  foreground 
job  is  terminated  and 
unloaded  via  UNLOAD  FG. 

?FG  PRESENT?  PIP  FATAL 

An  attempt  was  made  to  use  /0 
or  /S  while  a  foreground  job 
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was  still  in  memory.  Unload 
it  if  it  is  no  longer 
desired. 


?FIL  NAM? 

FILEX 

FATAL 

?FIL  NOT  FND? 

CSI 

FATAL 

FILEX 

FATAL 

LIBR 

FATAL 

MONITOR 

FATAL 

PIP 

FATAL 

?FILE? 

MONITOR 

FATAL 

7FILNAM.EXT  ALREADY 

EXISTS? 

FILEX 

FATAL 

?*FILE  FULL*?  EDIT  FATAL 

?FILE  NOT  FND?  LINKER  FATAL 

?*FILE  NOT  FND*?  EDIT  FATAL 

%FILES  ARE  DIFFERENT 

SRCCOM  INFORM 

?FIO  FILE  I/O  ERROR  AT  LINE  xxxxx 

BASIC  FATAL 


The  output  filename  was 
invalid  or  null. 

Input  file  was  not  found. 

The  input  file  was  not  found , 
or  the  "wild-card"  (*,*) 
construction  matched  none  of 
the  existing  files. 

One  of  the  input  files 
indicated  in  the  command  line 
was  not  found.  The  CSI 
prints  an  asterisk;  the 
command  may  be  reentered. 

File  specified  in  R ,  RUN, 
GET  ,  or  FRUN  command  not 
found. 

File  not  found  during  a 
delete,  copy,  or  rename 
operation. 

No  file  named  where  one  was 
expected. 


An  attempt  was  made  to  create 
the  named  file  (FILNAM.EXT) 
on  a  DOS  DECtape  when  a  file 
already  existed  under  the 
name  specified.  Use  /D  to 
delete  the  file,  and  retry 
the  transfer. 

Available  space  on  output 
file  was  full.  Type  a  CTRL  C 
and  a  CLOSE  monitor  command 
to  save  the  data  already 
written. 

Input  file  was  not  found. 

Attempted  to  open  a 
nonexistent  file  for  editing. 


Indicates  that  the  files 
compared  were  different. 


An  I/O  error  occurred.  All 
files  are  automatically 
closed. 
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FLOATING  CONSTANT  TOO  SMALL 

FORTRAN  FATAL 


?FNF  FILE  NOT  FOUND  AT  LINE  xxxxx 

BASIC  FATAL 


?FNO  FILE  NOT  OPEN  AT  LINE  xxxxx 

BASIC  FATAL 


7FORLIB  NOT  FND?  LINKER  FATAL 


?FTS  FILE  TOO  SHORT  AT  LINE  xxxxx 

BASIC  FATAL 


?FWN  FOR  WITHOUT  NEXT  AT  LINE  xxxxx 

BASIC  FATAL 


******  H  FORTRAN  INFORM 


7HANDLR?  MONITOR  FATAL 

7 HARD  I/O  ERROR?  LINKER  FATAL 

?*HDW  ERR*?  EDIT  FATAL 

I  MACRO  INFORM 


A  floating  constant  in  an 
expression  was  too  close  to 
zero  to  be  represented  in  the 
internal  format.  Use  zero  if 
possible. 


The  file  requested  was  not 
found  on  the  specified 
device. 


The  sequential  or  virtual 
memory  file  referenced  was 
not  open. 

The  user  indicated  via  the  /F 
switch  that  the  FORTRAN 
library,  FORLIB,  was  to  be 
linked  with  the  other  object 
modules  in  the  command  line, 
and  the  Linker  could  not  find 
FORLIB. OBJ  on  the  system 
device . 


The  sequential  file  space 
allocated  to  an  output  file 
was  inadequate. 


The  program  contained  a  FOR 
statement  without  a 
corresponding  NEXT  statement 
to  terminate  the  loop. 

xxxxx 

Program  GOSUBs  nested  to  more 
than  20  levels. 

Hollerith  string  or  quoted 
literal  string  longer  than 
255  characters  or  longer  than 
the  remainder  of  the 
statement.  The  statement  is 
aborted. 

Attempted  to  close  a  file 
with  no  handler  in  memory. 
The  file  cannot  be  closed. 

A  hardware  error  has 
occurred;  try  again. 

A  hardware  error  occurred 
during  I/O.  May  be  caused  by 
WRITE  LOCKed  device.  Try 
again. 

Illegal  character  detected. 
Illegal  characters  which  are 
also  non-printing  are 


7GND  GOSUBS  NESTED  TOO  DEEPLY  AT  LINE 

BASIC  FATAL 
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******  j  FORTRAN  INFORM 


?IDF  ILLEGAL  DEF  AT  LINE  xxxxx 

BASIC  FATAL 


?IDM  ILLEGAL  DIM  AT  LINE  xxxxx 

BASIC  FATAL 

?ILL  ARG?  EDIT  FATAL 


?ILL  ASECT?  LINKER  FATAL 


?ILL  CMD?  CSI  FATAL 

EDIT  FATAL 


FILEX  FATAL 


replaced  by  a  ?  on  the 
listing.  The  character  is 
then  ignored. 

Non-FORTRAN  character  used. 
The  line  contains  a  character 
that  is  not  in  the  FORTRAN 
character  set  and  is  not  in  a 
Hollerith  string  or  comment 
line.  The  character  is 
ignored  and  compilation 
continues . 


The  DEF  statement  contained 
an  error. 


Syntax  error  in  a  dimension 
statement. 

The  argument  specified  was 
illegal  for  the  command  used. 
A  negative  argument  was 
specified  where  a  positive 
one  was  expected  or  argument 
exceeds  the  range  +  or  - 
16,383. 

The  user  has  attempted  to 
place  an  .ASECT  above  1000  in 
a  foreground  link  or  to  place 
an  .ASECT  into  an  overlay 
foreground  link. 

Syntax  error. 

EDIT  did  not  recognize  the 
command  line  specified;  ED 
was  not  the  first  command 
issued  when  used  to  activate 
the  display  hardware. 

The  length  of  the  command 
line  exceeded  72  characters; 
the  command  line  was  not  in 
proper  CSI  format;  the  UIC 
exceeded  the  allowed  number 
of  characters  or  [  was  used 
without  ] ;  a  "wild-card" 
(*,*)  construction  was  used 
on  a  non- file  structured 
device;  no  output  or  no 
input  file  was  specified  for 
a  copy  operation;  or  more 
them  one  filename 
construction  (devsfilnam.ext) 
was  specified  on  either  side 
of  the  =  (<)  sign. 
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xxxxxx  ?ILL 


?ILL  DEV? 


LIBR  FATAL 


MONITOR  FATAL 


PIP  FATAL 


DEL?  LIBR  FATAL 


CSI  FATAL 

FILEX  FATAL 


LIBR  FATAL 


An  illegal  command  was  used 
in  the  command  line.  The  CSI 
prints  an  asterisk;  the 
command  may  be  reentered. 

Illegal  Keyboard  Monitor 
command  or  command  line  too 
long. 

The  command  specified  was  not 
syntactically  correct;  a 
device  name  is  missing  which 
should  be  specified,  a  switch 
argument  is  too  large,  a 
filename  is  specified  where 
one  is  inappropriate,  or  a 
non-file  structured  device  is 
specified  for  a 
file-structured  operation. 

An  attempt  was  made  to  delete 
from  the  library's  directory 
a  module  or  an  entry  point 
that  does  not  exist;  xxxxxx 
represents  the  module  or 
entry  point  name.  The  CSI 
prints  an  asterisk  and  waits 
for  the  user  to  enter  another 
command  line. 

Device  specified  does  not 
exist. 

The  device  handler  was  not 
found,  an  invalid  device  name 
was  used,  or  one  of  the 
following  was  attempted: 

RK  or  DT  was  not  used  for 
DOS/BATCH  (RSTS-11)  input  in 
a  copy  operation; 

DT  was  not  used  for  DOS/BATCH 
(RSTS-11)  output  in  a  zero  or 
delete  operation; 

DT  was  not  used  for  DOS/BATCH 
(RSTS-11)  output  in  a  copy 
operation ; 

DT  was  not  used  for 
DECsystem-10  input  in  any 
operation. 

An  illegal  device  was 
specified  in  the  command 
line.  The  CSI  prints  an 
asterisk;  the  command  may  be 
reentered. 
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MONITOR 

PIP 

FATAL 

FATAL 

Illegal  or  nonexistent 
device ,  or  an  attempt  was 
made  to  make  a  device  handler 
resident  for  use  with  a 
foreground  job  (dev=F)  when 
the  Single-Job  Monitor  was 
running. 

?*ILL  DEV*? 

EDIT 

FATAL 

Attempted  to  open  a  file  on 
an  illegal  device,  or 
attempted  to  use  display 
hardware  when  none  was 
available  (it  may  be  in  use 
by  the  other  job) . 

xxxxxx  ?ILL  INS? 

3 

LIBR 

FATAL 

An  attempt  was  made  to  insert 
a  module  into  a  library  which 
contains  the  same  entry  point 
as  an  existing  module, 
xxxxxx  represents  the  entry 
point  name.  The  CSI  prints 
an  asterisk;  a  new  command 
may  be  entered. 

?ILL  MAC? 

EDIT 

FATAL 

Delimiters  were  improperly 
used,  or  an  attempt  was  made 
to  enter  an  M  command  during 
execution  of  a  Macro  or  an  EM 
command  whil6  an  EM  was  in 
progress . 

?*ILL  NAME*? 

EDIT 

FATAL 

Filename  specified  in  EB,  EW, 
or  ER  was  illegal. 

ILL  REN? 

PIP 

FATAL 

Illegal  rename  operation. 
Usually  caused  by  different 
device  names  on  the  input  and 
output  sides  of  the  command 
string. 

xxxxxx  ?ILL  REPL? 

LIBR 

FATAL 

An  attempt  was  made  to 
replace  in  the  library  file  a 
module  which  does  not  already 
exist,  xxxxxx  represents  the 
module  name.  The  CSI  prints 
an  asterisk  and  waits  for  the 
user  to  enter  another  command 
line. 

?ILL  SWT? 

FILEX 

FATAL 

An  illegal  switch  was  used  in 
a  command  line  (e.g.,  a 
switch  not  listed  in  Table 
J-l). 

PIP 

FATAL 

Illegal  switch  or  switch 

combination. 

ILLEGAL  ADJACENT  OPERATOR 

FORTRAN 

INFORM 

Two  operators  (*,  /,  logical 

operators,  etc.)  were 
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illegally  placed  next  to  each 
other.  Examples  I/*J. 

? ILLEGAL  COMMAND?  PATCHO  FATAL 

A  command  line  was  not 
recognized,  or  it  was  not  in 
the  proper  format  for  the 
particular  command. 

ILLEGAL  DO  STATEMENT  TERMINATOR  **** 

FORTRAN  INFORM 

A  DO  statement  terminator 
must  not  be  a  GO  TO, 
arithmetic  IF,  RETURN,  or  DO 
statement  or  logical  IF 
containing  one  of  these 
statements . 

ILLEGAL  ELEMENT  IN  I/O  LIST 

FORTRAN  INFORM 

An  item,  expression,  or 
implied  DO  specifier  in  an 
I/O  list  was  of  illegal 
syntax. 

ILLEGAL  STATEMENT  ON  LOGICAL  IF 

FORTRAN  INFORM 

The  statement  contained  in  a 
logical  IF  must  not  be 
another  logical  IF  or  DO 
statement . 

ILLEGAL  TYPE  FOR  OPERATOR 

FORTRAN  INFORM 

An  illegal  variable  type  has 
been  used  with  an 
exponentiation  or  logical 
operator. 

ILLEGAL  USAGE  OR  MISSING  LEFT  PARENTHESIS 


FORTRAN  INFORM 

A  left  parenthesis  was 
required  but  not  found,  or  a 
variable  reference  or 
constant  was  illegally 
followed  by  a  left 
parenthesis. 

?ILN  ILLEGAL  NOW  BASIC  FATAL 

An  attempt  was  made  to 
execute  an  INPUT  statement  in 
immediate  mode. 

?ILR  ILLEGAL  READ  AT  LINE  xxxxx 

BASIC  FATAL 

Tried  to  open  a  write-only 
device  for  input  or  tried  to 
read  on  a  sequential  file 
open  for  output. 

?IN  ER?  PIP  FATAL 

Unrecoverable  error  reading 
file.  Try  again  (this  error 
is  ignored  during  /C 
operation) . 

?IN  ERR?  DUMP  FATAL 

A  hardware  error  occurred 
while  reading  the  input  file 
and  /G  was  not  specified  in 
the  command  line. 
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FILEX  FATAL 

LIBR  FATAL 


SRCCOM  FATAL 


IN  LINE  nnnnn  MSG#  m  text 

FORTRAN 


IN  LINE  %WARNING%  MSG#  m  text 

FORTRAN 


7INCORRECT  FILE  SPEC? 

PATCH  FATAL 

? INPUT  ERROR?  EXPAND  FATAL 

?INSUFFICIENT  CORE?  EXPAND  FATAL 


A  device  error  occurred  on 
input. 

An  unrecoverable 

hardware/software  error  has 
occurred  while  processing  an 
input  file.  The  CSI  prints 
an  asterisk  and  waits  for 
another  command  to  be 
entered. 

A  hardware  error  occurred  in 
reading  input. 


Errors  reported  by  the 
secondary  phase  of  „  the 
compiler.  nnnnn  is  *  the 
internal  sequence  number  of 
the  statement ,  m  specif iies 
the  error  number ,  text  is 
explanation  of  error?  see 
individual  listings  for  text. 


Indicates  a  condition  which 
may  be  potentially  dangerous 
at  execution  time  or  which 
may  present  compatibility 
problems  with  other  FORTRAN 
compilers.  m  specifies  the 
error  number  and  text  is 
explanation  of  error;  see 
individual  listings  for  text. 


The  response  to  the  MFILE 
NAME--"  message  was  not  of 
the  correct  form.  Try  again. 

Hardware  error  in  reading  an 
input  file. 

Not  enough  memory  to  store 
macro  definitions. 


MACRO  FATAL 


PATCH  FATAL 


There  were  too  many  symbols 
in  the  program  being 
assembled.  Try  dividing 
program  into 
separately-assembled  sub¬ 
programs  . 

PATCH  did  not  have  enough 
memory  to  hold  the  file's 
device  handler  plus  the 
internal  " segment  table  w . 
This  message  should  not 
occur. 
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INTEGER  OVERFLOW  FORTRAN  INFORM 


INVALID  COMPLEX  CONSTANT 

FORTRAN  INFORM 

INVALID  DIMENSIONS  FOR  ARRAY  **** 

FORTRAN  INFORM 


INVALID  DO  TERMINATOR  ORDERING  AT  LABEL 

FORTRAN  INFORM 


INVALID  EQUIVALENCE  FORTRAN  INFORM 


INVALID  FORMAT  SPECIFIER 

FORTRAN  INFORM 


INVALID  IMPLICIT  RANGE  SPECIFIER 

FORTRAN  INFORM 


INVALID  LOGICAL  UNIT 

FORTRAN  INFORM 


INVALID  OCTAL  CONSTANT 

FORTRAN  INFORM 


INVALID  OPTIONAL  LENGTH  SPECIFIER 

FORTRAN  INFORM 


INVALID  RADIX50  CONSTANT 

FORTRAN  INFORM 

INVALID  RECORD  FORMAT 

FORTRAN  INFORM 


? INVALID  RELOC  REG?  PATCH  FATAL 


An  integer  constant  or 
expression  value  must  not 
fall  outside  the  range  -32767 
to  +32767. 

A  complex  constant  has  been 
improperly  formed. 


An  attempt  was  made  while 
dimensioning  an  array  to 
explicitly  specify  zero  as 
one  of  the  dimensions. 


**** 


DO  loops  were  incorrectly 
nested. 

Illegal  equivalence,  or 
equivalence  that  was 
contradictory  to  a  previous 
equivalence. 

A  format  specifier  was  not 
the  label  of  a  FORMAT 
statement  or  an  array  name. 


Illegal  implicit  range 
specifier?  i.e.,  non- 
alphabetic  specifier,  or 
specifier  range  was  in 
reverse  alphabetic  order. 


A  logical  unit  reference 
must  be  an  integer  variable 
or  constant  in  the  range  1  to 
99. 


An  octal  constant  was  too 
large  or  contained  a  digit 
other  than  0-7. 


A  data  type  declaration 
optional  length  specifier  was 
illegal.  For  example,  REAL* 4 
and  REAL* 8  are  legal,  but 
REAL* 6  is  not. 

Illegal  character  detected 
in  a  RADIX50  constant. 

The  third  parenthetical 
argument  in  a  DEFINE  FILE 
statement  must  be  a  single 
character  U. 

Tried  to  reference  a 
relocation  register  outside 
the  range  0-7. 
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7INVALID  SEG  NO?  PATCH  FATAL  The  segment  number  Ss  did  not 

exist. 

INVALID  STATEMENT  IN  BLOCK  DATA 


FORTRAN 

INFORM 

It  is  illegal 

to 

have  any 

executable 

or 

FORMAT 

statements  in 

a 

BLOCK  DATA 

subprogram. 

INVALID  STATEMENT  LABEL  REFERENCE 

FORTRAN  INFORM  Reference  has  been  made  to  a 

statement  number  that  is  of 
illegal  construction.  GO  TO 
999999  is  illegal  since  the 
statement  number  is  too  long. 


INVALID  SUBROUTINE  OR  FUNCTION  NAME 

FORTRAN  INFORM  A  name  used  in  a  CALL 

statement  or  function 
reference  was  not  valid. 
Example:  use  of  an  array 

name  in  a  CALL  statement 
subroutine  name  reference. 


INVALID  TARGET  FOR  ASSIGNMENT 

FORTRAN  INFORM 


The  left  side  of  an 
arithmetic  assignment 
statement  was  not  a  variable 
name  or  array  element 
reference. 


INVALID  TYPE  SPECIFIER 

FORTRAN  INFORM  An  unrecognizable  data  type 

was  used. 

INVALID  USAGE  OF  FUNCTION  OR  SUBROUTINE  NAME 

FORTRAN  INFORM  A  function  name  cannot  appear 

in  a  DIMENSION,  COMMON,  DATA, 
EQUIVALENCE,  or  Data  Type 
Declaration  statement. 


INVALID  VARIABLE  NAME 

FORTRAN  INFORM 


?I/0  ERROR  ON  CHANNEL  n? 

MACRO  FATAL 


******  K  FORTRAN  INFORM 


A  variable  name  was  missing, 
contained  an  illegal 
character,  or  did  not  begin 
with  an  alphabetic  character. 


A  hardware  error  occurred 
while  attempting  to  read  from 
or  write  to  the  device  on  the 
channel  specified  in  the 
message. 

Illegal  statement  label 
definition.  Illegal 
(non-numeric)  character  in 
statement  label.  The  illegal 
statement  label  is  ignored 
and  compilation  continues. 
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t 


L 


MACRO  INFORM 


******  l  FORTRAN  INFORM 


LABEL  ON  DECLARATIVE  STATEMENT 

FORTRAN  INFORM 


?LDA  FILE  ERROR? 

LINKER 

FATAL 

7LIBR  FIL  ILL 

REPL? 

LIBR 

FATAL 

LINE  TOO  LONG 

EXPAND 

INFORM 

?LP  NOT  FND? 

DUMP 

FATAL 

?LTL  LINE  TOO 

LONG 

BASIC 

FATAL 

M 

MACRO 

INFORM 

?/M  ODD  VAL? 

LINKER 

FATAL 

******  JJJ 

FORTRAN 

INFORM 

Line  buffer  overflow;  i.e., 
input  line  greater  than  132 
characters .  Extra  characters 
on  a  line  (more  than  72 
decimal)  are  ignored  in 
terminal  mode. 

Line  too  long.  There  are 
more  than  80  characters  in  a 
line;  this  diagnostic  is 
issued  before  the  line 
containing  too  many 
characters.  The  line  is 
truncated  to  80  characters 
and  compilation  continues. 

It  is  illegal  to  place  a 
label  on  a  declarative 
statement. 

There  was  a  hardware  problem 
with  the  device  specified  for 
LDA  output  or  the  device  is 
full. 

The  user  has  specified  that  a 
library  file  be  replaced  by 
another  library  file.  Only 
object  modules  can  be 
replaced. 

A  line  has  become  longer  than 
132  characters. 

A  line  printer  handler  was 
not  available  on  the  system. 

The  line  typed  was  longer 
than  120  characters;  the 
line  buffer  overflows. 

Multiple  definition  of  a 
label.  A  label  was 
encountered  which  was 
equivalent  (in  the  first  six 
characters)  to  a  previously 
encountered  label. 

An  odd  value  has  been 
specified  for  the  stack 
address.  Control  returns  to 
the  Linker  and  another 
command  line  may  be 
indicated. 

Multiply  defined  label.  The 
label  is  ignored. 
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MACRO  ALREADY  DEFINED 

EXPAND  INFORM 

MACRO (S)  NOT  FOUND  EXPAND  INFORM 

7M-BAD  FETCH  xx  MONITOR  FATAL 

7M-DIR  10  ERR  xx  MONITOR  FATAL 

7M-DIR  OVLFO  xx  MONITOR  FATAL 

7M-DIR  UNSAFE  xx  MONITOR  FATAL 


7M-FP  TRAP  xx  MONITOR  FATAL 

7M-ILL  ADDR  xx  MONITOR  FATAL 


A  macro  was  defined  more  than 
once. 

Macros  listed  in  an  . MCALL 
statement  were  not  found  in 
SYSMAC.8K  (make  sure 
SYSMAC.8K  is  present  on 
system) . 

Either  an  error  occurred 
while  reading  a  device 
handler  from  SY,  or  the 
address  at  which  the  handler 
was  to  be  loaded  is  illegal, 
xx  represents  the  address 
plus  2  of  the  location  where 
the  error  occurred. 

An  error  occurred  doing  I/O 
in  the  directory  of  a  device 
(e.g. ,  .ENTER  on  a 
write-locked  device) .  xx 
represents  the  address  plus  2 
of  the  location  where  the 
error  occurred. 

No  more  directory  segments 
were  available  for  expansion 
(occurs  during  creation  via 
file  .ENTER) .  xx  represents 
the  address  plus  2  of  the 
location  where  the  error 
occurred. 

In  F/B  only,  this  message  may 
appear  in  addition  to  any  of 
the  other  M-  diagnostics 
listed.  It  indicates  that 
the  error  occurred  while  the 
USR  was  updating  a  device 
directory.  One  or  more  files 
on  that  device  may  be  lost, 
xx  represents  the  address 
plus  2  of  the  location  where 
the  error  occurred. 

A  floating-point  exception 
trap  occurred,  and  the  user 
program  had  no  .SFPA 
exception  routine  active  (see 
Chapter  9) .  xx  represents  the 
address  plus  2  of  the 
location  where  the  error 
occurred. 

Under  the  F/B  Monitor,  an 
address  specified  in  a 
monitor  call  was  odd  or  was 
not  within  the  job's  limits, 
xx  represents  the  address 
plus  2  of  the  location  where 
the  error  occurred. 
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7M-ILL  CHAN  xx 


?M— ILL  EMT  xx 


7M-ILL  USR  xx 


?M— NO  DEV  XX 


7M-OVLY  ERR  xx 


7M-SWAP  ERR  xx 


7M-TRAP  TO  4  xx 
?r  1-TRAP  TO  10  xx 


?MAP  FILE  ERROR? 


MONITOR  FATAL 


MONITOR  FATAL 


MONITOR  FATAL 


MONITOR  FATAL 


MONITOR  FATAL 


MONITOR  FATAL 


MONITOR  FATAL 


LINKER  FATAL 


A  channel  number  was 
specified  which  was  too 
large,  xx  represents  the 
address  plus  2  of  the 
location  where  the  error 
occurred. 

An  EMT  was  executed  which  did 
not  exist;  i.e.,  the 
function  code  was  out  of 
bounds •  xx  represents  the 
address  plus  2  of  the 
location  where  the  error 
occurred. 

The  USR  was  called  from  a 
completion  routine.  This 
error  does  not  have  a  soft 
return  (i,e,,  .SERR  will  not 
inhibit  this  message;  see 
Chapter  9).  xx  represents  the 
address  plus  2  of  the 
location  where  the  error 
occurred, 

A  READ/WRITE  operation  was 
tried  but  no  device  handler 
was  in  memory  for  it,  xx 
represents  the  address  plus  2 
of  the  location  where  the 
error  occurred, 

A  user  program  with  overlays 
has  failed  to  successfully 
read  an  overlay.  xx 
represents  the  address  plus  2 
of  the  location  where  the 
error  occurred. 

A  hard  I/O  error  occurred 
while  the  system  was 
attempting  to  swap  KMON  or 
the  USR.  This  is  usually 
caused  by  a  write-locked 
system  device.  Under  the  S/J 
Monitor ,  this  may  cause  the 
system  to  halt.  xx 
represents  the  address  plus  2 
of  the  location  where  the 
error  occurred. 

The  job  has  referenced 
illegal  memory ,  an  illegal 
instruction  was  used,  etc. 
xx  indicates  where  the 
failure  occurred. 

There  was  a  hardware  problem 
with  the  device  specified  for 
map  output  or  the  device  was 
full. 
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MISSING  ASSIGNMENT  OPERATOR 

FORTRAN  INFORM 

The  first  operator  seen  in  an 
arithmetic  assignment 
statement  was  not  an  equal 
sign  (=) .  Examples  I+J=K. 

MISSING  COMMA  FORTRAN  INFORM 

The  comma  delimiter  was 
expected  but  was  not  found. 
See  the  section  of  the 
FORTRAN  Reference  Manual  that 
describes  the  general  form  of 
the  statement  in  question. 

MISSING  COMMA  IN  MACRO  ARG 

EXPAND  INFORM 

Found  spaces  or  tabs  within  a 
macro  argument;  try  using 
brackets  around  the  argument; 
e.g.,  <arg  with  spaces>. 

MISSING  DELIMITER  IN  EXPRESSION 

FORTRAN  INFORM 

Two  operands  have  been  placed 
next  to  each  other  in  an 
expression ,  with  no  operator 
between  them. 

MISSING  DOT  EXPAND  INFORM 

A  macro  name  or  argument  name 
did  not  begin  with  a  dot. 

7MISSING  END  IN  MACRO? 

EXPAND  FATAL 

End  of  input  was  encountered 
while  storing  a  macro 
definition;  probably  missing 
an  .ENDM. 

MISSING  LABEL  FORTRAN  INFORM 

A  statement  label  was 
expected  but  not  found. 
Example:  ASSIGN  J  TO  I.  A 
valid  statement  label 
reference  should  precede  fT0* 
but  does  not. 

MISSING  RIGHT  PARENTHESIS 

FORTRAN  INFORM 

A  right  parenthesis  was 
expected  but  not  found. 
Examples  READ (5,100,) .  The 
first  non-blank  character 
after  the  format  reference 
should  be  a  right  parenthesis 
but  is  not. 

MISSING  QUOTATION  MARK 

FORTRAN  INFORM 

In  a  FIND  statement,  the 
logical  unit  number  and 
record  number  must  be 
separated  by  a  single 
quotation  mark. 

MISSING  VARIABLE  FORTRAN  INFORM 

A  variable  was  expected  but 
not  found.  Examples  ASSIGN 
100  TO  1.  A  variable  name 
should  follow  the  'TO1  but 
does  not. 
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MISSING  VARIABLE  OR  CONSTANT 

FORTRAN  INFORM 

Looked  for  an  operand 
(variable  or  constant)  but 
found  a  delimiter  (comma , 
parenthesis ,  etc,).  Example: 
WRITE ().  A  unit  number  should 
follow  the  open  parenthesis , 
but  a  delimiter  (close 
parenthesis)  is  encountered 
instead. 

MODES  OF  VARIABLE  ****  AND  DATA  ITEM  DIFFER 


FORTRAN  INFORM 

The  data  type  of  each 
variable  and  its  associated 
data  list  item  must  agree  in 
a  DATA  statement. 

7M0DULE  NOT  FOUND?  PATCHO  INFORM 

The  module  requested  in  a 
POINT  command  was  not  found 
in  the  input  file  between  the 
position  of  the  file  at  the 
time  of  the  point  and  the 
end. 

?M0RE  THAN  15  CHANGES? 

PATCHO  FATAL 

Too  many  changes  have  been 
specified  for  a  particular 
module.  The  patch  should  be 
broken  up  into  several  steps. 

?M0RE  THAN  5  CSECTS  REQUIRE  CHANGE? 

PATCHO  FATAL 

An  attempt  has  been  made  to 
patch  locations  in  too  many 
different  CSECTs.  The  patch 
should  be  made  in  several 
steps. 

MULT  DEF  OF  XXXXXX  LINKER  FATAL 

The  symbol ,  xxxxxx,  was 

defined  more  than  once. 

MULTIPLE  DECLARATION  FOR  VARIABLE  **** 

FORTRAN  INFORM 

A  variable  cannot  appear  in 
more  than  one  data  type 
declaration  statement  or 
dimensioning  statement. 

?MUST  OPEN  WORD?  PATCH  FATAL 

The  @  command  was  typed  when 
a  byte  location  was  open. 

?MUST  SPECIFY  SEG?  PATCH  FATAL 

The  address  referenced  was 
not  in  the  root  section;  a 
segment  number  S:  must  be 
used. 

N  MACRO  INFORM 

Number  containing  8  or  9  had 
decimal  point  missing. 

NAME  DOESN'T  MATCH 

EXPAND  INFORM 

Optional  name  given  in  .ENDM 
directive  did  not  match  name 
given  in  corresponding  .MACRO 
directive. 
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?NBF  NEXT  BEFORE  FOR  AT  LINE  xxxxx 

BASIC  FATAL 

?NER  NOT  ENOUGH  ROOM  AT  LINE  xxxxx 

BASIC  FATAL 

NESTED  MACROS  EXPAND  INFORM 

?NIF  ASEMBL  FATAL 


?N0  ADDR  OPEN? 

PATCH 

FATAL 

?N0  CLOCK? 

MONITOR 

FATAL 

?N0  CORE? 

LIBR 

FATAL 

?N0  FG? 

MONITOR 

FATAL 

?*N0  FILE*? 

EDIT 

FATAL 

?N0  FILE  OPEN 

PATCHO 

FATAL 

?N0  INPUT? 

LINKER 

FATAL 

?N0  INPUT  FILE? 

EXPAND 

FATAL 

MACRO 

FATAL 

NO  NAME 

EXPAND 

INFORM 

?*N0  ROOM*? 

EDIT 

FATAL 

The  NEXT  statement 
corresponding  to  a  FOR 
statement  preceded  the  FOR 
statement. 


There  was  not  enough  room  on 
the  selected  device  for  the 
specified  number  of  output 
blocks. 

A  macro  was  defined  or 
invoked  within  another  macro. 

No  input  file  was  specified 
and  there  must  be  at  least 
one  input  file. 

The  <line  feed>,  t  or  @ 
command  was  typed  when  no 
location  was  open. 

No  KWllL  clock  was  available 
for  the  TIME  command. 

Available  free  memory  has 
been  used  up.  The  current 
command  is  aborted  and  the 
CSI  prints  an  asterisk;  a 
new  command  may  be  entered. 

A  SUSPEND,  RSUME ,  or  UNLOAD 
FG  command  was  given,  but  no 
foreground  job  was  in  memory. 

Attempted  to  read  or  write 
when  no  file  was  open. 

An  attempt  was  made  to  use  a 
command  other  than  DEC  or 
HELP  before  an  OPEN  command 
was  issued. 

No  input  files  were 
specified. 

There  must  be  at  least  one 
input  file. 

No  input  file  was  specified 
and  there  must  be  at  least 
one  input  file. 

A  macro  definition  had  no 
name. 

Attempted  to  Insert,  Save, 
Unsave,  Read,  Next,  Change  or 
Exchange  when  there  was  not 
enough  room  in  the 
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appropriate  buffer.  Delete 
unwanted  buffers  to  create 
more  room  or  write  text  to 
the  output  file. 

?*N0  TEXT*?  EDIT  FATAL 

Attempted  to  call  in  text 
from  the  Save  Buffer  when 
there  was  no  text  available. 

?N0  SYS  ACTION?  PIP  WARNING 

The  /Y  switch  was  not 
included  with  a  command 
specified  on  a  ,SYS  file. 
The  command  is  executed  for 
all  but  the  .SYS  files.  A 
*.*  transfer  is  most  likely 
to  cause  this  message. 

?NO  UFD?  FILEX  FATAL 

The  specified  UFD  was  not 
found  on  the  DOS  input  disk. 

NON-STANDARD  STATEMENT  ORDERING 

FORTRAN  WARNING 

Non-adherence  to  statement 
ordering  requirements  may 
cause  error  conditions  on 
other  FORTRAN  compilers. 

?NOT  IN  PROGR  BOUNDS? 

PATCH  FATAL 

Tried  to  open  a  location 

beyond  the  end  of  the  file. 

?NPR  NO  PROGRAM  BASIC  FATAL 

The  RUN  command  has  been 
specified #  but  no  program  has 
been  typed  in. 

?NSM  NUMBERS  AND  STRINGS  MIXED  AT  LINE  xxxxx 


BASIC  FATAL 

String  and  numeric  variables 
may  not  appear  in  the  same 
expression ,  nor  may  they  be 
set  equal  to  each  other  (as 
in  A$=2) . 

NUMBER  IN  FORMAT  STATEMENT  NOT  IN  RANGE 

FORTRAN  INFORM 

An  integer  constant  in  a 
FORMAT  statement  was  greater 
than  255  or  was  zero. 

0  FORTRAN  FATAL 

Unrecoverable  error  occurred 
while  the  Compiler  was 
writing  the  object  file 
(.OBJ).  Possibly  insufficient 
output  file  space. 

SOLUTION  -  Rectify  hardware 
problem ,  or  make  more  space 
for  output. 

MACRO  INFORM 

Opcode  error.  Directive  out 
of  context. 

/0  IGNORED  LINKER  WARNING 

Overlays  have  been  specified 
in  the  wrong  order  (see 
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Error  Message  Summary 


?ODD 

ADDRESS? 

PATCH 

FATAL 

?ODD 

BOTTOM  ADDR? 

PATCH 

FATAL 

?ODF 

ASEMBL 

FATAL 

70FFSET? 

PATCHO 

FATAL 

?00D  OUT  OF  DATA  AT  LINE  xxxxx 

BASIC  FATAL 

?OUT  ER?  PIP  FATAL 


?OUT  ERR?  DUMP  FATAL 

FILEX  FATAL 

LIBR  FATAL 

SRCCOM  FATAL 

?OUT  FIL?  PIP  FATAL 


overlay  restrictions) ;  the 
overlay  switch  is  ignored. 

Tried  to  open  a  word  address 
which  was  odd.  (Use  "\".) 

The  bottom  address  specified 
or  contained  in  location  42 
of  an  overlay  file  was  odd. 

No  room  to  continue  writing 
output;  try  to  compress 
device  with  PIP. 

The  offset  supplied  in  a  WORD 
or  BYTE  command  was  not  an 
octal  number ,  or  was  in 
improper  format. 


The  data  list  was  exhausted 
and  a  READ  requested 
additional  data. 

Unrecoverable  error  writing 
file.  Perhaps  a  hardware  or 
checksum  error;  try 
recopying  file.  Also  may  be 
caused  by  an  attempt  to 
compress  a  larger  device  to  a 
smaller  one  or  by  not  enough 
room  when  creating  a  file. 
The  system  takes  the  largest 
space  available  and  divides 
it  in  half  before  attempting 
to  insert  the  file.  Try  the 
[]  construction  or  /X  switch. 

A  hardware  error  occurred 
while  writing  an  output  file, 
or  the  output  device  was 
full. 

A  device  error  occurred  on 
output . 

An  unrecoverable 
hardware/software  error  has 
occurred  while  processing  an 
output  file.  The  CSI  prints 
an  asterisk  and  waits  for  the 
user  to  enter  another 
command. 

A  hardware  error  occurred  in 
writing  output  file,  or 
output  device  full. 

Illegal  output  file 
specification  or  missing 
output  file. 


P-27 


Error  Message  Summary 


70UTPUT  DEVICE 

FULL? 

EXPAND 

FATAL 

No  room  to  continue  writing 
output.  Try  to  compress  the 
device  with  PIP. 

MACRO 

FATAL 

No  room  to  continue  writing 
output.  Try  to  compress 
device  with  PIP. 

70UTPUT  ERROR? 

PATCHO 

FATAL 

A  hardware  error  (or  possibly 
a  write-lock  condition) 
occurred  while  attempting  to 
write  the  output  file. 

70UTPUT  FILE  TOO  SMALL? 

PATCHO 

FATAL 

The  space  allocated  to  the 
output  file  was  too  small. 
This  may  be  corrected  by 
compressing  the  device  with 
PIP  (if  enough  total  space  is 
free  on  the  device) ,  or  by 
using  another  device  for 
output . 

70UTPUT  FULL? 

LINKER 

FATAL 

The  output  device  was  full. 

?OVF  OVERFLOW 

AT  LINE  xxxxx 
BASIC 

FATAL 

The  result  of  a  computation 
was  too  large  for  the 
computer  to  handle. 

?OVR  COR? 

MONITOR 

FATAL 

Attempted  to  GET  or  RUN  a 
file  that  was  too  big. 

P 

FORTRAN 

FATAL 

Optimizer  push  down  overflow. 
Statement  too  complex ,  or  too 
many  common  subexpressions 
occurred  in  one  basic  block 
of  a  program. 

SOLUTION  -  Simplify  complex 

statements. 

MACRO 

INFORM 

Phase  error.  A  label's 
definition  of  value  varied 
from  one  pass  to  another. 

******  p 

FORTRAN 

INFORM 

Statement  contained 
unbalanced  parentheses.  The 
statement  is  aborted. 

P-SCALE  FACTOR 

NOT  IN  RANGE  - 
FORTRAN 

127  to  +127 
INFORM 

P-scale  factors  must  fall  in 
the  range  -127  to  +127. 

?P ARAMS? 

MONITOR 

FATAL 

Bad  parameters  were  typed  to 
the  SAVE  command. 

PARENTHESES  NESTED  TOO  DEEPLY 

FORTRAN 

INFORM 

Group  repeats  in  a  FORMAT 
statement  have  been  nested 

too  deeply. 
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Error  Message  Summary 


?PROG 

HAS  NO  SEGS? 

PATCH 

FATAL 

The  file  specified  as  an 

overlay  file  was  not. 

?PTB 

PROGRAM  TOO  BIG 

BASIC 

FATAL 

The  line  just  entered  caused 
the  program  to  exceed  the 
user  code  area. 

?PWF 

POWER  FAIL  AT 

LINE  xxxxx 

BASIC  FATAL 

A  power  fail  occurred  while 
the  specified  line  was  being 
executed. 

Q 

MACRO 

INFORM 

Questionable  syntax.  There 
were  missing  arguments  or  the 
instruction  scan  was  not 
completed  or  a  carriage 
return  was  not  immediately 
followed  by  a  line  feed  or 
form  feed. 

R 

FORTRAN 

FATAL 

Unrecoverable  hardware  error 
occurred  while  the  Compiler 
was  reading  source  file. 

SOLUTION  -  Rectify  hardware 

problem. 

MACRO 

INFORM 

Register-type  error.  An 
invalid  use  of  or  reference 
to  a  register  has  been  made. 

?RBG 

RETURN  BEFORE 

GOSUB  AT 
BASIC 

LINE  xxxxx 
FATAL 

A  RETURN  was  encountered 
before  execution  of  a  GOSUB 
statement. 

READ 

ERROR? 

PATCH 

FATAL 

File  I/O  error  in  reading. 

7REB00T? 

PIP 

INFORM 

.SYS  files  have  been 

transferred,  renamed, 

compressed  or  deleted  from 
the  system  device.  It  may  be 
necessary  to  reboot  the 
system.  The  actual  reboot 
operation  must  not  be 
performed  until  PIP  returns 
with  the  prompting  asterisk 
for  the  next  command. 

REFERENCE  TO  INCORRECT  TYPE  OF  LABEL  **** 

FORTRAN  INFORM  A  statement  label  reference 

that  should  be  a  label  on  a 
FORMAT  statement  was  not  such 
a  label,  or  a  statement  label 
reference  that  should  be  a 
label  on  an  executable 
statement  was  not  such  a 
label. 
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Error  Message  Summary 


REFERENCE  TO  UNDEFINED  STATEMENT  LABEL 

FORTRAN  INFORM 


?REL  FILE  ERR? 


LINKER 


FATAL 


?REL  FIL  I/O  ER?  MONITOR  FATAL 


?ROOM? 


PIP 


FATAL 


FORTRAN  FATAL 


****** 


FORTRAN  INFORM 


?SAV  FILE  ERR? 


LINKER 


FATAL 


A  reference  has  been  made  to 
a  statement  number  that  has 
not  been  defined  anywhere  in 
the  program  unit. 

The  Linker  encountered  a 
problem  writing  the  REL  file; 
try  again. 

Either  the  program  requested 
was  not  a  REL  file  or  a 
hardware  error  was 
encountered  trying  to  read  or 
write  the  file. 

Insufficient  space  following 
file  specified  with  a  /T 
switch. 

Subexpression  stack  overflow; 
statement  too  complex. 

SOLUTION  —  Simplify  complex 
statements . 

Syntax  error  (multiple  equal 
signs,  etc.).  Statement  not 
of  the  general  FORTRAN 
statement  form.  The 
statement  is  aborted. 

The  Linker  encountered  a 
problem  writing  the  save 
image  file;  try  again. 


?SOB  SUBSCRIPT  OUT  OF  BOUNDS  AT  LINE  xxxxx 

BASIC  FATAL  The  subscript  computed  was 

greater  than  32,767  or  was 
outside  the  bounds  defined  in 
the  DIM  statement. 


?*SRCH  FAIL*? 


EDIT  FATAL  The  text  string  specified  in 

a  Get,  Find  or  Position 
command  was  not  found  in  the 
available  data. 


?SSO  STRING  STORAGE  OVERFLOW  AT  LINE  xxxxx 


BASIC 


FATAL 


?STACK  ADDRESS  UNDEFINED  OR  IN  OVERLAY? 

LINKER  WARNING 


STATEMENT  NUMBER  MUST  BE  UNLABELED 

FORTRAN  INFORM 


P-30 


There  was  not  enough  memory 
available  to  store  all  the 
strings  used  in  the  program. 


The  stack  address  specified 
by  the  /M  switch  was  either 
undefined  or  in  an  overlay. 
The  stack  address  is  set  to 
the  system  default. 


A  data,  subroutine,  function, 
block  data,  arithmetic 
statement  function 


Error  Message  Summary 


STATEMENT  TOO  COMPLEX 

FORTRAN  INFORM 


?STL  STRING  TOO  LONG  AT  LINE  xxxxx 

BASIC  FATAL 


definition,  or  declarative 
statement  must  not  be 
labeled. 


An  arithmetic  statement 
function  had  more  than  10 
dummy  arguments ,  or  the 
statement  was  too  long  to 
compile.  Break  it  up  into  2 
or  more  smaller  statements. 


The  maximum  length  of  a 
string  in  a  BASIC  statement 
is  255  characters. 


SUBROUTINE  OR  FUNCTION  STATEMENT  MUST  BE  FIRST 

FORTRAN  INFORM  A  SUBROUTINE,  FUNCTION  or 

BLOCK  DATA  statement,  if 
present,  must  be  the  first 
statement  in  a  program  unit. 

SUBSCRIPT  OF  ARRAY  ****  NOT  IN  RANGE 

FORTRAN  INFORM  Array  subscripts  that  were 

constants  or  constant 
expressions  were  checked  to 
see  if  they  were  within  the 
bounds  of  the  array's 
dimensions. 


?SV  FIL  I/O  ER?  MONITOR  FATAL 

? SWITCH  ERROR?  SRCCOM  FATAL 

?SWT  ERR?  FILEX  FATAL 


?SY  I/O  ER?  MONITOR  FATAL 


7SYMBOL  TABLE  OVERFLOW? 

LINKER  FATAL 


I/O  error  on  .SAV  file  in 
SAVE  (output)  or  R,  RUN,  GET, 
or  FRUN  (input)  command. 

An  invalid  switch  was  found 
or  a  switch  other  than  /L  was 
given  a  value. 

An  attempt  was  made  to  use 
more  them  one  /S  or  /T  switch 
in  a  command  line  (only  one 
is  allowed) ;  an  attempt  was 
made  to  use  more  than  one 
transfer  mode  switch  (/I,  /P, 
/A)  or  more  than  one 
operation  switch  (/D,  /L,  /F, 
/Z)  in  a  command  line  (only 
one  of  each  is  allowed) . 

I/O  error  on  system  device 
(usually  reading  or  writing 
scratch  area) . 


There  were  too  many  global 
symbols  used  in  the  program. 
Retry  the  link  using  the  /S 
switch.  If  the  error  still 
occurs,  the  link  cannot  take 
place. 
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Error  Message  Summary 


?SYN  SYNTAX  ERROR  AT  LINE  xxxxx 

BASIC  FATAL 

The  program  has  encountered 
an  unrecognizable  statement. 
Common  examples  of  syntax 
errors  are  misspelled 
commands  and  unmatched 
parentheses ,  and  other 
typographical  errors. 

Wrong  number  of  arguments  was 
used  in  a  function,  or 
illegal  delimiter  in  a 
function. 

SYNTAX  EXPAND  INFORM 

A  macro  directive  was  not 

constructed  correctly. 

SYNTAX  ERROR  FORTRAN  INFORM 

Check  the  general  form  of  the 
statement  with  the  general 
form  outlined  in  the  FORTRAN 
LANGUAGE  REFERENCE  MANUAL 
section  that  describes  the 
type  of  statement. 

SYNTAX  ERROR  IN  INTEGER  OR  FLOATING  CONSTANT 


FORTRAN  INFORM 

An  integer  or  floating 
constant  has  been  incorrectly 
formed.  For  example ,  1.23.4 
is  an  illegal  floating 
constant  because  it  contains 
two  decimal  points. 

T  FORTRAN  FATAL 

Memory  Overflow. 

SOLUTION  -  Break  up  program 
into  subprograms  or  compile 
on  larger  machine. 

MACRO  INFORM 

Truncation  error.  A  number 
generated  more  than  16  bits 
of  significance  or  an 
expression  generated  more 
than  8  bits  of  significance 
during  the  use  of  the  .BYTE 
directive. 

TARGET  MUST  BE  ARRAY 

FORTRAN  INFORM 

The  third  argument  in  an 
ENCODE  or  DECODE  statement 
must  be  an  array  name. 

?TIM?  MONITOR  FATAL 

The  TIME  command  argument  is 
illegal. 

?TLT  LINE  TOO  LONG  TO  TRANSLATE 

BASIC  FATAL 

Lines  are  translated  as 
entered ,  and  the  line  just 
entered  exceeded  the  area 
available  for  translation. 
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Error  Message  Summary 


?TMO?  ASEMBL  FATAL 

TOO  MANY  ARGS 

EXPAND  INFORM 


?TOO  MANY  OUTPUT  FILES? 

MACRO  FATAL 


LINKER  FATAL 


?TOO  MUCH  DIFFERENCE? 

SRCCOM  FATAL 


Too  many  output  files  were 
specified. 


A  macro  directive  had  more 
than  30  arguments. 


Too  many  output  files  were 
specified. 

The  Linker  allows 

specification  of  only  two 
output  files. 

More  than  310  (octal)  lines 
of  difference  between  two 
files  were  found. 


TRANSFER  ADDRESS  UNDEFINED  OR  IN  OVERLAY 


U 


LINKER 


MACRO 


WARNING 


INFORM 


******  u 


FORTRAN  INFORM 


The  transfer  address  was  not 
defined  or  was  in  an  overlay. 


Undefined 
undefined 
encountered 
evaluation 
Relative  to 


symbol.  An 

symbol  was 
during  the 
of  an  expression, 
the  expression. 


the  undefined  symbol 
assigned  a  value  of  zero. 


is 


Statement  could  not  be 
identified  as  any  legal 
FORTRAN  statement.  The 
statement  is  aborted. 


?UFN  UNDEFINED  FUNCTION  AT  LINE  xxxxx 

BASIC  FATAL 


The  function  called  was  not 
defined  by  the  program  or  was 
not  loaded  with  BASIC. 


?ULN  UNDEFINED  LINE  NUMBER  AT  LINE  xxxxx 

BASIC  FATAL  The  line  number  specified  in 

an  IF ,  GO  TO  or  GOSUB 
statement  did  not  exist 
anywhere  in  the  program. 


UNDEF  GLBLS  LINKER  WARNING 


UNDEFINED  GLOBALS  LINKER  WARNING 

xxxxxx 

xxxxxx 


A  load  map  has  been  requested 
and  there  were  undefined 
globals. 

The  globals  listed  (xxxxxx) 
were  undefined. 


UNLABELED  FORMAT  STATEMENT 

FORTRAN  INFORM 

USAGE  OF  VARIABLE  ****  INVALID 

FORTRAN  INFORM 


All  FORMAT  statements  must  be 
labeled. 


An  attempt  was  made  to 
EXTERNAL  a  common  variable. 
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Error  Message  Summary 


am  array  variable,  or  a  dummy 
argument  or  an  attempt  was 
made  to  place  in  COMMON  a 
dummy  argument  or  external 
name. 


VARIABLE  ****  INVALID  IN  ADJUSTABLE  DIMENSION 

FORTRAN  INFORM  A  variable  used  as  an 

adjustment  dimension  must  be 
an  integer  dummy  argument  in 
the  subprogram  unit. 

VARIABLE  ****  IS  NOT  WORD  ALIGNED 

FORTRAN  WARNING  Placing  a  non- LOGICAL* 1 

variable  or  array  after  a 
LOGICAL* 1  variable  or  array 
in  COMMON  or  equivalencing 
non-LOGICAL*l  variables  or 
arrays  to  logical* 1  variables 
or  arrays  may  cause  this 
condition.  An  attempt  to 
reference  the  variable  at 
runtime  will  cause  an  error 
condition. 


VARIABLE  ****  NAME  EXCEEDS  SIX  CHARACTERS 


FORTRAN  WARNING 


W  FORTRAN  FATAL 


?WLO  WRITE  LOCKOUT  AT  LINE  xxxxx 

BASIC  FATAL 

7WRITE  ERROR?  PATCH  FATAL 

7WR0NG  NUMBER  OF  OUTPUT  FILES? 

EXPAND  FATAL 

WRONG  NUMBER  OF  SUBSCRIPTS  FOR  ARRAY 

FORTRAN  INFORM 


A  variable  name  of  more  than 
six  characters  was  specified. 
The  first  six  characters  were 
used  as  the  true  variable 
name .  Other  FORTRAN 
Compilers  may  treat  this  as 
an  error  condition. 

Unrecoverable  error  occurred 
while  the  Compiler  was 
writing  listing  file. 
Possibly,  listing  file  space 
was  not  large  enough. 

SOLUTION  -  Rectify  hardware 
problem,  or  make  more  space 
for  listing  file. 


Tried  to  open  a  read-only 
device  for  output,  or  tried 
to  write  on  a  sequential  or 
virtual  file  opened  for  input 
only. 

File  I/O  error  in  writing. 


There  must  be  exactly  one 
output  file. 

**** 

An  array  reference  did  not 
have  the  same  number  of 
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Error  Message  Summary 


Y 


FORTRAN  FATAL 


Z 


FORTRAN  FATAL 


MACRO  INFORM 


devs/Z  ARE  YOU  SURE? 

PIP  ACTION 


0  NON-FORTRAN  ERROR  CALL 

FORTRAN  FATAL 


1  INTEGER  OVERFLOW 

FORTRAN  FATAL 


2  INTEGER  ZERO  DIVIDE 

FORTRAN  FATAL 


3  COMPILER  GENERATED  ERROR 

FORTRAN  FATAL 


4  COMPUTED  GO  TO  OUT  OF  RANGE 

FORTRAN  WARNING 


subscripts  as  specified  when 
the  array  was  dimensioned. 

Code  generation  stack 
overflow  -  statement  too 
complex. 

SOLUTION  —  Simplify  complex 
statements . 

Compiler  error. 

SOLUTION  —  Report  this  error 
to  your  local  software 
support  representative. 
Please  include  program 
listing. 

Instruction  which  was  not 
compatible  among  all  members 
of  the  PDP-11  family  (11/05, 
11/20,  11/40,  11/45). 


Asks  for  confirmation  from 
the  user  before  zeroing  a 
device. 


A  TRAP  has  occurred  with  an 
unrecognizable  error  code. 


During  an  arithmetic 
operation,  an  integer's  value 
has  exceeded  32767  in 
magnitude. 


During  an  integer  mode 
arithmetic  operation  an 
attempt  was  made  to  divide  by 
zero. 


An  attempt  was  made  to 
execute  a  FORTRAN  statement 
in  which  the  compiler 
detected  errors. 


The  integer  variable  or 
expression  in  a  computed  GO 
TO  statement  was  less  than  1 
or  greater  than  the  number  of 
statement  label  references  in 
the  list.  Control  is  passed 
to  the  next  executable 
statement. 
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Error  Message  Summary 


5  INPUT  CONVERSION  ERROR 

FORTRAN  COUNT: 3 

During  a  formatted  input 
operation  an  illegal 
character  was  detected  in  an 
input  field.  A  value  of  0  is 
returned. 

6  OUTPUT  CONVERSION  ERROR 

FORTRAN  IGNORE 

During  a  formatted  output 
operation  the  value  of  a 
particular  number  could  not 
be  output  in  the  specified 
field  length  without  loss  of 
significant  digits.  The 
field  is  filled  with  *'s. 

10  FLOATING  OVERFLOW 

FORTRAN  COUNT : 3 

During  an  arithmetic 
operation  a  real  value  has 
exceeded  the  largest 
representable  real  number.  A 
value  of  0  is  returned. 

11  FLOATING  UNDERFLOW 

FORTRAN  IGNORE 

During  an  arithmetic 
operation  a  real  value  has 
become  less  than  the  smallest 
representable  real  number, 
and  has  been  replaced  with  a 
value  of  zero. 

12  FLOATING  ZERO  DIVIDE 

FORTRAN  FATAL 

During  a  real  mode  arithmetic 
operation  an  attempt  was  made 
to  divide  by  zero. 

13  SQRT  OF  NEGATIVE  NUMBER 

FORTRAN  COUNT : 3 

An  attempt  was  made  to  take 
the  square  root  of  a  negative 
number.  The  result  is 
replaced  by  0. 

14  UNDEFINED  EXPONENTIATION  OPERATION 

FORTRAN  FATAL 

An  attempt  was  made  to 
perform  an  illegal 
exponentiation  operation. 
For  example  -3. **.5  is 
illegal  because  the  result 
would  be  an  imaginary  number. 

15  LOG  OF  NEGATIVE  NUMBER 

FORTRAN  FATAL 

An  attempt  was  made  to  take 
the  logarithm  of  a  negative 
number. 

16  WRONG  NUMBER  OF  ARGUMENTS 

FORTRAN  FATAL 

One  of  the  FORTRAN  Library 
functions,  or  System 
Subroutines  which  checks  for 
such  an  occurrence,  has  been 
called  with  an  improper 
number  of  arguments. 
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Error  Message  Summary 


20  INVALID  CHANNEL  NUMBER 

FORTRAN 


FATAL 


21  NO  AVAILABLE  CHANNELS 

FORTRAN 


FATAL 


22  INPUT  RECORD  TOO  LONG 

FORTRAN 


FATAL 


23  HARDWARE  I/O  ERROR 

FORTRAN 


FATAL 


An  illegal  logical  unit 
number  has  been  specified  in 
an  I/O  statement.  A  logical 
unit  number  must  be  an 
integer  between  1  and  99. 


An  attempt  was  made  to  have 
too  many  devices 
simultaneously  open  for  I/O. 
The  maximum  number  of  active 
channels  is  six  by  default, 
but  this  number  may  be 
changed  at  compile  time. 


During  an  input  operation  a 
record  was  encountered  that 
was  longer  than  the  maximum 
record  length.  The  default 
maximum  record  length  is  133 
(decimal)  bytes,  but  this 
number  may  be  altered  at 
compile  time. 


A  hardware  error  has  been 
detected  during  an  I/O 
operation. 


24  ATTEMPT  TO  READ/WRITE  PAST  END  OF  FILE 


FORTRAN  FATAL 


25  ATTEMPT  TO  READ  AFTER  WRITE 

FORTRAN  FATAL 


26  RECURSIVE  I/O  NOT  ALLOWED 

FORTRAN 


FATAL 


27  ATTEMPT  TO  USE  DEVICE  NOT  IN  SYSTEM 

FORTRAN  FATAL 

28  OPEN  FAILED  FOR  FILE 

FORTRAN  FATAL 


If  this  occurred  during  a 
WRITE,  more  space  was  needed 
to  contain  the  output  file. 


An  attempt  was  made  to  read 
after  writing  on  a  file.  A 
WRITE  must  be  followed  by  a 
REWIND  or  BACKSPACE  before  a 
read  operation  can  be 
performed. 


An  expression  in  the  I/O  list 
of  a  WRITE  statement  has 
caused  initiation  of  another 
READ  or  WRITE  operation. 
This  can  happen  if  a  FUNCTION 
that  performs  I/O  is 
referenced  in  an  expression 
in  a  WRITE  statement  I/O 
list. 


Self-explanatory. 

A  file  could  not  be  found. 
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Error  Message  Summary 


29  NO  ROOM  FOR  DEVICE  HANDLER 

FORTRAN  FATAL 


There  was  not  enough  free 
memory  left  to  accommodate  a 
specific  device  handler. 


30  NO  ROOM  FOR  BUFFERS 

FORTRAN  FATAL 


There  was  not  enough  free 
memory  left  to  set  up 
required  I/O  buffers. 


31  NO  AVAILABLE  RT-11  CHANNEL 

FORTRAN  FATAL 


32  FMTD-UNFMTD-RANDOM  I/O  TO  SAME  FILE 

FORTRAN  FATAL 


More  than  the  maximum  number 
of  RT-11  channels ,  15 f  were 
requested  to  be 
simultaneously  opened  for 
I/O. 


An  attempt  was  made  to 
perform  any  combination  of 
formatted #  unformatted 9  or 
random  access  I/O  to  the  same 
file. 


33  ATTEMPT  TO  READ  PAST  END  OF  RECORD 

FORTRAN  FATAL 


An  attempt  was  made  to  read  a 
larger  record  than  actually 
existed  in  a  file. 


34  UNFMTD  I/O  TO  TTY  OR  LPT 

FORTRAN  FATAL 


35  ATTEMPT  TO  OUTPUT  TO  READ  ONLY  FILE 

FORTRAN  FATAL 


An  attempt  was  made  to 
perform  an  unformatted  write 
operation  on  the  terminal  or 
line  printer. 


Self-explanatory, 


36  BAD  FILE  SPECIFICATION  STRING 

FORTRAN  FATAL 


Self-explanatory . 


37  RANDOM  ACCESS  READ/WRITE  BEFORE  DEFINE  FILE 

FORTRAN  FATAL  A  random  access  READ  or  WRITE 

operation  was  attempted 
before  a  DEFINE  FILE  was 
performed. 

38  RANDOM  I/O  NOT  ALLOWED  ON  TTY  OR  LPT 

FORTRAN  FATAL  Random  access  I/O  was 

illegally  attempted  on  the 
terminal  or  line  printer. 

39  RECORD  LARGER  THAN  RECORD  SIZE  IN  DEFINE  FILE 

FORTRAN  FATAL  A  record  was  encountered  that 

was  larger  than  that 
specified  in  the  DEFINE  FILE 
statement  for  a  random  access 
file. 
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Error  Message  Summary 

40  REQUEST  FOR  A  BLOCK  LARGER  THAN  65535 

FORTRAN  FATAL  An  attempt  was  made  to 

reference  an  absolute  disk 
block  address  greater  than 
65535. 


41  DEFINE  FILE  ATTEMPTED  ON  AN  OPEN  UNIT 

FORTRAN  FATAL  An  open  file  must  be  closed 

before  another  DEFINE  FILE 
can  be  performed  on  that 
unit. 


42  MEMORY  OVERFLOW  COMPILING  OBJECT  TIME  FORMAT 


FORTRAN  FATAL 


The  OTS  has  run  out  of  free 
memory  while  scanning  an 
array  format  that  was 
generated  at  run  time. 


43  SYNTAX  ERROR  IN  OBJECT  TIME  FORMAT 

FORTRAN  FATAL 


44  2ND  RECORD  REQUEST  IN  ENCODE/DECODE 

FORTRAN  FATAL 


A  syntax  error  was 
encountered  while  the  OTS  was 
scanning  an  array  format  that 
was  generated  at  run  time. 


ENCODE  and  DECODE  will 
operate  only  on  a  single 
record  at  a  time. 


45  INCOMPATIBLE  VARIABLE  AND  FORMAT  TYPES 


FORTRAN 


FATAL 


46  INFINITE  FORMAT  LOOP 

FORTRAN 


FATAL 


47  ATTEMPT  TO  STORE  OUTSIDE  PARTITION 

FORTRAN  FATAL 


60  STACK  OVERFLOWED 


FORTRAN  FATAL 


An  attempt  was  made  to  output 
a  real  variable  with  an 
integer  field  descriptor  or 
an  integer  variable  with  a 
real  field  descriptor. 


The  format  associated  with  an 
I/O  statement  that  includes 
an  I/O  list  has  no  field 
descriptors  to  use  in 
transferring  those  variables. 


In  an  attempt  to  store  data 
into  a  subscripted  variable, 
the  address  calculated  for 
the  array  element  in  question 
did  not  lie  within  the 
section  of  memory  allocated 
to  the  job.  The  subscript  in 
question  is  out-of-bounds. 
(Message  is  issued  only  when 
bounds-checking  modules  have 
been  installed  in  FORLIB.) 


The  hardware  stack  has 
overflowed.  Proper  traceback 
may  be  impaired. 


P-39 


Error  Message  Summary 


61  ILLEGAL  MEMORY  REFERENCE 

FORTRAN  FATAL  This  may  be  any  type  of  BUS 

error,  most  probably  an 
illegal  memory  address 
reference. 

62  FORTRAN  START  FAIL 

FORTRAN  FATAL  The  program  has  been  loaded 

into  memory  but  there  was  not 
enough  free  memory  remaining 
for  the  OTS  to  initialize 
work  space  and  buffers. 

63  ILLEGAL  INSTRUCTION 

FORTRAN  FATAL  The  program  has  attempted  to 

execute  an  illegal 

instruction,  e.g.,  floating 
point  arithmetic  instruction 
on  a  machine  with  no  floating 
point  hardware. 
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Absolute  address 

A  binary  number  that  is  assigned  as  the 
address  of  a  fixed  memory  storage  loca¬ 
tion. 

Absolute  block  numbers 

Any  blocks  which  use  block  0  of  a  physi¬ 
cal  device  as  a  base.  Relative  blocks 
use  the  start  of  a  file  as  a  base. 

Absolute  section 

That  portion  of  a  program  in  which  the 
programmer  specifies  the  physical  (abso¬ 
lute)  locations  of  data  items ,  using  the 
•ASECT  assembler  directive. 

Addressing  mode 

The  portion  of  a  PDP-11  machine  instruc¬ 
tion  which  specifies  how  the  argument  is 
to  be  referenced. 

Alphanumeric  character 
string 

A  command  string  containing  any  of  the  26 
alphabetic  characters  A-Z,  the  numeric 
characters  0-9 ,  space  and  certain  special 
characters . 

Argument 

A  variable  or  constant  which  is  given  in 
the  call  of  a  subroutine  as  information 
to  it?  a  variable  upon  whose  value  the 
value  of  a  function  depends?  the  known 
reference  factor  necessary  to  find  an  item 
in  a  table  or  array  (i.e.,  the  index). 

Argument  block 

A  block  of  memory  used  to  transmit  pro¬ 
grammed  request  arguments  to  the  monitor. 

Array 

A  set  or  list  of  elements ,  usually  sub¬ 
scripted  variables  or  data. 

ASCII 

American  Standard  Code  for  Information 
Interchange.  Established  by  American 
National  Standards  Institute  to  stan¬ 
dardize  a  binary  code  for  alphanumeric 
characters . 

Assembler 

A  program  that  translated  symbolic  op¬ 
codes  into  machine  language  and  assigns 
memory  locations  for  variables  and  con¬ 
stants  . 

Assembler  directives 

The  mnemonics  used  in  the  assembly  language 
programs  to  control  or  direct  the  assembly 
process . 

Assembly  language 

A  symbolic  language  that  translates  di¬ 
rectly  into  machine  language  instructions. 
Usually  there  is  a  one-to-one  relation  be¬ 
tween  assembly  language  instructions  and 
machine  language  instructions. 
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Asynchronous 


Autoincrement  mode 


Background  program 


Backup  file 


Bad  blocks 


Base  address 


Base  segment 


Baud 


Binary 


Bit 


Blocks 


1.  Pertaining  to  the  scheduling  of  hard¬ 
ware  operations  by  ready  and  done 
signals  rather  than  by  time  intervals. 

2.  Pertaining  to  the  method  of  data  trans¬ 
mission  in  which  each  character  is 
sent  with  its  own  synchronizing  infor¬ 
mation  . 

Mode  of  operation  wherein  the  contents  of 
the  register  are  incremented  immediately 
after  being  used  as  address  of  the  operand. 

A  program  operating  automatically,  under 
low  priority,  when  higher  priority  (fore¬ 
ground)  programs  are  not  using  system 
resources . 

A  copy  of  a  file  created  for  protection 
in  case  the  primary  file  is  inadvertently 
destroyed. 

A  defective  block  of  storage  on  any  type 
of  magnetic  storage  medium  that  produces 
a  hardware  error  when  attempting  to  read 
or  write  in  the  block. 

A  given  address  from  which  an  absolute 
address  is  derived  by  combination  with  a 
relative  address.  An  address  constant. 

The  portion  of  an  overlayed  program  that 
is  always  memory  resident;  same  as  root 
segment. 

A  unit  of  signaling  speed.  In  a  code  in 
which  all  characters  have  the  same  length, 
one  baud  corresponds  to  a  rate  of  one 
signal  element  per  second,  usually  one 
bit  per  second. 

Pertaining  to  the  number  system  having  a 
base  or  radix  of  two.  In  this  system 
numbers  are  represented  by  Is  and  Os. 
Counting  to  ten  in  binary:  1,  10,  11,  100, 
101,  110,  111,  1000,  1001,  1010. 

Contraction  of  "Binary  digit" ,  a  bit  is 
the  smallest  unit  of  information  in  a 
binary  system  of  notation.  It  is  the 
choice  between  two  possible  states,  usually 
designated  one  (1)  and  zero  (0) . 

A  set  of  consecutive  machine  words,  char¬ 
acters  or  digits  handled  as  a  unit,  par¬ 
ticularly  in  reference  to  I/O.  Each  type 
of  mass  storage  has  its  own  block  size, 
its  own  smallest  unit  of  storage  (e.g. 
PDP-11  DECtape  has  256io  16-bit  words  per 
block) .  See  Data  Block. 
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Bootstrap 

A  program  of  several  instructions  whose 
purpose  is  to  load  and  (usually)  start  a 
complex  system  of  programs. 

Bottom  address 

The  lowest  memory  address  in  which  a  pro¬ 
gram  is  located. 

Bounds 

The  limits  a  program  may  operate  within. 

Breakpoint 

A  preset  point  in  a  user  program  where 
control  passes  to  a  debugging  routine. 

Buffer 

A  temporary  storage  area  which  may  be  a 
special  register  or  an  area  of  storage. 
Buffers  are  often  used  to  hold  data  being 
passed  between  processes  or  devices  which 
operate  at  different  speeds  or  different 
times . 

Byte 

A  group  of  binary  digits  usually  operated 
upon  as  a  unit  (typically  1/2  word) . 

Carry  bit 

A  bit  in  the  program  status  word  indicating 
a  carry  from  the  most  significant  bit  in 
the  operation;  also  a  common  method  of 
indicating  a  program  request  failure. 

Central  processing  unit 

The  part  of  the  computer  containing  the 
Arithmetic  and  Logical  Unit,  the  Instruc¬ 
tion  Control  Unit,  timing  generators  and 

I/O  interfaces  of  the  basic  system. 

Chaining 

A  programming  technique  which  involves 
dividing  a  routine  into  sections  with  each 
section  terminated  by  a  call  to  the  next 
section. 

Channel  number 

Logical  identifier  in  range  0  to  255io 
assigned  to  a  file  used  by  RT-11  Monitor. 
Data  blocks  in  an  open  file  may  be  referred 
to  by  channel  number. 

Channel  status  word 

A  word  associated  with  each  I/O  channel 
in  RT-11  that  preserves  the  status  of 
that  channel. 

Character-oriented 

Referring  to  editing  operations  on  a  single 
character.  See  also  Line-oriented. 

Checksum 

A  value  representing  the  sum  of  all  bytes 
in  a  program.  When  the  program  is  loaded, 
the  sum  of  the  bytes  can  be  compared  with 
the  checksum  to  make  sure  that  the  entire 
program  has  been  loaded  correctly. 

Clock 

A  time-keeping  or  frequency-measuring  de¬ 
vice  within  the  computer  system. 

Closed  location 

A  location  whose  contents  are  not  available 
for  examination  and  change. 
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Co-resident  overlay 
routines 

Overlay  routines  that  are  simultaneously 
resident  in  memory. 

Command  string 

A  series  of  characters  which  specify  the 
input/output  devices,  files,  and  switches. 

Command  String 

Interpreter 

The  portion  of  the  RT-11  system  software 
which  accepts  an  ASCII  string  input  and 
interprets  the  string  as  input  and  output 
files  and  switches. 

Completion  routines 

An  optional  user-supplied  routine  that  is 
called  at  the  completion  of  an  operation. 

Compress 

To  move  into  one  area  all  the  free  (unused) 
blocks  that  are  interspersed  in  the  direc¬ 
tory  and  files  on  a  specified  device. 

Concatenate 

To  combine  many  files  into  one  file. 

Condition  codes 

The  four  bits  of  the  Program  Status  Word 
in  the  PDP-11  Processor  that  preserve  the 
results  (negative,  zero,  carry,  overflow) 
of  the  instruction  just  completed. 

Configuration 

A  particular  selection  of  computer,  periph¬ 
erals,  and  interfacing  equipment  that  are 
functioning  together.  A  list  of  the  de¬ 
vices  and  computers  of  a  computer  system. 

Console  device 

The  interface,  or  communication  device, 
between  the  operator  and  the  computer, 
which  contains  indicator  lights,  switches, 
knobs  and  sometimes  a  keyboard  to  permit 
manual  operation  of  the  device. 

Constant  register 

A  logical  register  in  ODT  or  PATCH  which 
is  used  to  store  an  often-used  constant. 

Context  switching 

The  saving  of  key  registers  and  other 
memory  areas  prior  to  switching  between 
jobs,  as  in  timesharing  or  multiprogramming. 

Contiguous 

Code  which  resides  in  memory  or  on  a  periph¬ 
eral  device  immediately  adjacent  to  other 
sections  of  code  or  data. 

Control  Section  (CSECT) 

A  named,  contiguous  part  of  a  program. 

CSECT ' s  are  denoted  by  the  directives 
".CSECT"  and  ".ASECT"  in  the  MACRO  Assembler 
Language.  CSECT' s  are  collected  and  as¬ 
signed  addresses  by  the  Linker. 

Core  memory 

The  main  high-speed  storage  of  a  computer 
in  which  binary  data  is  represented  by  the 
switching  polarity  of  magnetic  cores. 
Semi-conductor  memory  is  higher  speed  than 
core  memory,  but  semi-conductor  memory  is 
more  expensive  and  volatile. 
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Cross  reference  table 
(CREF) 

A  list  of  all  or  a  subset  of  symbols  in 
source  program  and  statements  where  they 
were  defined  or  used. 

Cursor 

On  a  display  device,  a  symbol  that  appears 
to  indicate  the  location  of  the  pointer . 

Data  block 

A  logical  grouping  of  data,  usually  associa¬ 
ted  with  input  or  output.  Typical  data 
blocks  involved  in  RT-11  are  256  words 
long. 

Data  format 

The  form  or  structure  of  information,  par¬ 
ticularly  in  an  I/O  file.  RT-11  has  several 
standard  data  formats  such  as  ASCII  and 
formatted  binary. 

Debug 

To  detect,  locate,  and  correct  mistakes 
in  a  program. 

Default 

A  specification  assigned  by  system  pro¬ 
gram  when  user  specification  is  omitted. 

Delimiter 

A  character  that  separates,  terminates 
and  organizes  elements  of  a  statement  or 
program. 

Device  block 

A  section  of  code  that  specifies  a  physi¬ 
cal  device  and  filename  for  an  RT-11  pro¬ 
grammed  request. 

Device  directory 
listing 

• 

A  list  of  all  files  on  a  specified  device. 
List  contains  all  files  with  associated 
creation  dates,  total  free  blocks  on  de¬ 
vice,  and  number  of  blocks  used  by  files. 
Magtape  and  cassette  directories  omit 
some  information.  See  Directory. 

Device  handlers 

Routines  that  perform  I/O  for  specific 
storage  devices  and  translate  logical 
block  numbers  to  physical  disk,  tape  or 
drum  addresses.  These  routines  also 
handle  error  recovery  and  provide  device 
independence  in  conjunction  with  opera¬ 
ting  systems. 

Direct  assignment 

User  definition  of  symbol  and  associated 
value . 

Directive 

see  Assembler  directives 

Directory 

An  area  of  a  mass  storage  device  that 
describes  the  layout  of  the  data  on  that 
device  in  terms  of  file  names,  length  and 
location . 

Disk 

A  mass  storage  device.  Basic  unit  is  an 
electromagnetic  platter  on  which  data  is 
magnetically  recorded.  Features  random 
access  and  faster  access  time  than  mag¬ 
netic  tape. 
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Display  unit 

A  device  that  provides  a  visual  represen¬ 
tation  of  data. 

Double  buffered  I/O 

An  input  (or  output)  operation  using  two 
buffers  to  achieve  overlap.  While  one 
buffer  is  being  used  by  the  CPU  program, 
the  other  is  being  read  from  (or  written 
to)  by  an  I/O  device. 

Dummy  file 

A  file  used  only  to  hold  space  on  a  stor¬ 
age  device. 

Editor 

A  program  which  interacts  with  the  pro¬ 
grammer  to  enter  new  programs  into  the 
computer  and  edit  them  as  well  as  modify 
existing  programs .  Editors  are  language 
independent  and  will  edit  anything  in 
alphanumeric  representation. 

EMT 

A  PDP-11  machine  instruction  (operation 
codes  from  104000-104377) .  EMTs  are  most 
often  used  for  monitor  communication. 

Entry  point 

A  point  in  a  subroutine  to  which  control 
is  transferred  when  the  subroutine  is 
called. 

Entry  point  table 

A  table,  kept  by  the  Librarian  program, 
of  the  names  and  locations  of  the  routines 
available  in  the  library. 

Entry  symbol 

A  global  symbol  defined  in  an  object  mod¬ 
ule  that  can  be  referred  to  by  other  ob¬ 
ject  modules. 

Error  flag 

Condition  indicating  an  error  has  occurred. 
If  the  C  bit  is  set  on  return  from  an 

RT-11  call,  an  error  occurred.  Thus,  the 

C  bit  set  is  the  RT-11  error  flag. 

Exception 

An  unusual  condition  (e.g.,  a  floating 
point  exception  is  an  overflow) . 

Expressions 

A  combination  of  variables,  constants,  and 
operators  (as  in  a  mathematical  expression) 

External  symbol 

A  symbolic  name  which  is  defined  in  one 
assembly  or  compilation  and  can  be  refer¬ 
enced  in  another.  The  . GLOBL  directive 
is  used  to  indicate  external  symbols  to 
the  MACRO  assembler. 

Fatal  error 

An  error  which  makes  continued  processing 
impossible  (e.g.,  running  out  of  symbol 
table  space  is  usually  a  fatal  error) . 

File  allocation  scheme 

The  method  used  to  store  data  on  I/O  de¬ 
vices.  RT-11  uses  a  contiguous  structure. 

File  gap 

A  fixed  length  of  blank  tape  separating 
files  on  a  recording  medium. 
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File  structured  device 


Filler  characters 

Flag 

Floating-point 

Foreground  program 

Formatted  binary  block 

Fragmented 
Free  blocks 
General  registers 

Global  symbol 

Global  symbol  directory 

Handler 
Hardware  mode 

High  level  language 


A  device  on  which  data  is  given  names  and 
arranged  in  files;  the  device  also  con¬ 
tains  a  directory  of  these  names . 

Null  characters  output  to  a  device  to  give 
it  time  to  perform  unusually  long  opera¬ 
tions  (such  as  return  the  carriage)  with¬ 
out  explicitly  waiting. 

A  variable  or  register  used  to  record  the 
status  of  a  program  or  device.  In  the 
latter  case  it  is  sometimes  called  a  de¬ 
vice  flag. 

A  number  system  in  which  the  position  of 
the  radix  point  is  indicated  by  one  part 
(the  exponent  part) ,  and  another  part 
represents  the  significant  digits,  the 
fractional  part  (e.g.,  5.39X108  -  Decimal; 
137.3X84  -  octal;  101.10X213  -  Binary). 

A  program  of  high  priority  that  utilizes 
machine  facilities  when  and  as  needed, 
but  allows  less  critical  background  work 
to  be  performed  in  otherwise  unused  time. 

A  data  structure  used  to  hold  binary  in¬ 
formation,  usually  to  be  read  or  written 
to  a  data  file.  For  example,  an  object 
module  produced  by  the  MACRO  assembler 
consists  of  formatted  binary  blocks. 

Having  many  empty  entries  scattered  over 
a  device. 

Areas  of  a  file  structured  device  which 
are  unused. 

A  set  of  eight  general  purpose  registers 
available  for  use  as  accumulators,  as 
auto  index  registers  or  as  pointers. 
General  registers  6  and  7  serve  as  the 
hardware  stack  pointer  and  program  counter 
respectively. 

Any  symbol  accessible  to  other  programs . 
Linkage  must  be  supplied  by  a  linker. 

The  portion  of  an  object  module  which  des¬ 
cribes  all  external  symbols  and  CSECT 
names  which  are  defined  or  referenced  by 
the  object  module. 

see  Device  handler 

For  magnetic  tapes  and  cassettes.  Allows 
full  user  control  over  position  and  record 
size.  (As  opposed  to  software  mode.) 

A  language  in  which  single  statements  may 
result  in  more  than  one  machine  language 
instruction,  e.g.,  BASIC,  FORTRAN,  COBOL. 
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Image  mode 

Implied  argument 

Indexing 
Initialize 
Internal  symbol 

Interrupt  service 
Interrupt 

Iterations 
Job  status  word 

Keyboard  monitor 

Label 

LDA  format  file 
Library 

Library  header 

Light  pen 


A  mode  of  data  transfer  in  PIP  in  which 
a  file  is  copied  without  change  of  any 
kind. 

An  argument  which  is  assumed  by  the  pro¬ 
gram,  whether  or  not  it  is  explicitly 
stated  by  the  user. 

Using  a  variable  index  register  as  an 
offset  into  a  table. 

To  set  counters,  switches,  addresses  and 
variables  to  zero  or  other  starting  values. 

A  symbolic  name  which  is  known  only  within 
the  assembly  or  compilation  where  it  is 
defined.  Symbols  are  internal  by  default. 

routine  Routine  entered  when  an  external  interrupt 
occurs . 

1.  To  break  the  normal  operation  of  the 
routine  being  executed  and  pass  con¬ 
trol  to  a  specific  location  -  generally 
accompanied  by  saving  the  state  of 

the  current  routine  so  that  control 
can  return  later. 

2.  The  signal  which  causes  the  break. 

Repetitions  of  a  portion  of  a  program. 

A  word  in  the  RT-11  communications  region 
containing  bit  flags  indicating  the  status 
of  the  program  currently  in  memory. 

(KM.ON)  Program  that  provides  communication  be¬ 

tween  the  user  at  the  console  and  the 
RT-11  system. 

One  or  more  characters  used  to  identify 
a  source  language  statement  or  line. 

see  Load  image  file 

A  collection  of  standard  routines  which 
can  be  incorporated  into  other  programs. 

Section  of  code  that  contains  the  current 
status  of  the  library,  including  version, 
date  and  time  of  creation  or  update,  rela¬ 
tive  starting  address  of  entry  point  table, 
number  of  EPT  entries  and  placing  of  next 
module  to  be  inserted  into  the  library 
file. 

A  device  resembling  a  pencil  or  stylus 
which  can  detect  a  fluorescing  spot  on  a 
CRT  screen.  Used  to  input  information  to 
a  CRT  display  system. 
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Line-oriented 

Referring  to  editing  operations  on  an  en¬ 
tire  line  of  text.  See  also  Character- 
oriented. 

Load  image  file 

A  program  that  can  be  executed  in  stand¬ 
alone  environment  without  the  aid  of 
relocation. 

Local  symbol 

A  symbol  used  only  within  the  program  in 
which  it  is  defined  (all  non-global  sym¬ 
bols)  . 

Location  counter 

A  counter  kept  by  an  assembler  to  determine 
the  address  assigned  to  an  instruction  or 
constant  being  assembled. 

Logical  name 

A  user-defined  name  assigned  as  an  alter¬ 
nate  name  for  a  physical  device.  Useful 
for  redirecting  I/O  when  device  originally 
specified  is  unavailable. 

Loop 

A  sequence  of  instructions  that  is  executed 
repeatedly  until  a  terminal  condition 
occurs.  Also ,  used  as  a  verb  meaning  to 
execute  this  circle  of  instructions  while 
waiting  for  the  ending  condition. 

Macro 

An  instruction  in  a  source  language  that 
is  equivalent  to  a  specified  sequence  of 
machine  instructions ,  or  a  command  in  a 
command  language  that  is  equivalent  to  a 
specified  sequence  of  commands. 

Macro  symbol 

Symbol  used  as  macro  name  in  operator  field. 

Mainstream  code 

Any  code  which  is  not  executing  as  a  result 
of  a  completion  routine. 

Mask  word 

A  combination  of  bits  that  is  used  to 
clear  selected  portions  of  any  word,  char¬ 
acter,  byte,  or  register  while  retaining 
other  parts  for  use.  Also,  to  clear  these 
selected  locations  with  a  mask. 

Memory  address 

An  address  in  memory  used  to  store  data. 

Memory  image 

An  exact  copy  of  a  portion  of  memory. 

RT-11  save  image  files  ( .SAV)  are  memory 
images . 

Mnemonic 

Alphabetic  representation  of  a  function  or 
octal  machine  instruction. 

Mode 

A  state  or  method  of  program  operation. 
Command  mode  causes  user  input  to  be  in¬ 
terpreted  as  a  command;  text  mode  causes 
user  input  to  be  interpreted  as  alphanumeric 
data,  etc. 

Module 

A  routine  which  handles  a  particular  func¬ 
tion. 
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Monitor 


Monitor  System 

Multi-region 

Nesting 

Non-file  structured 
device 

Null 

Object  code 
Off-line 

Offset 

On-line 

Open  location 
Operand 

Operating  system 
Operator 


The  collection  of  routines  which  schedules 
resources ,  I/O ,  system  programs ,  and 
user  programs,  and  obeys  keyboard  commands 
in  a  Monitor  System. 

Editors,  assemblers,  compilers,  loaders, 
interpreters,  data  management  programs 
and  other  utility  programs  all  automated 
for  the  user  by  a  monitor. 

A  term  describing  the  RT-11  overlay  struc¬ 
ture  in  which  there  may  exist  multiple 
independent  areas  of  high-speed  memory 
(regions)  in  which  overlays  may  occur. 

1.  Including  a  program  loop  inside  another 
program  loop,  or  other  similar  occur¬ 
rences  within  one  another. 

2 .  Algebraic  nesting  such  as  (A+B+ (C+D) ) 
where  execution  proceeds  from  the 
innermost  level  to  the  outermost  level. 

A  device  used  only  for  input  or  output,  and 
not  storage,  of  a  file  (e.g.,  line  printer, 
or  card  reader)  or  which  is  a  sequential 
device . 

Characters  with  ASCII  code  000. 

The  result  after  assembling  or  compiling 
source  code.  Machine  code. 

Pertaining  to  equipment,  devices  or  events 
which  are  not  under  direct  control  of  the 
computer . 

The  difference  between  a  location  of 
interest  and  some  known  base  location. 

Pertaining  to  equipment,  devices  and 
events  which  are  in  direct  communication 
with  the  CPU  and  thereby  under  its  con¬ 
trol  in  some  way. 

Location  whose  contents  have  been  printed 
for  examination;  contents  can  be  changed. 

1.  A  quantity  which  is  affected,  manipu¬ 
lated  or  operated  upon. 

2 .  The  contents  of  the  field  following 
the  operator  of  an  assembler  instruc¬ 
tion. 

A  program  for  automating  a  programmer's 
use  of  software.  A  Monitor  System. 

That  symbol  or  code  which  indicates  an 
action  or  operation  to  be  performed. 
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Overlay 


Overlay  segment 

Overlay-structured 

Page  of  text 

Parameter 

Patch 

Peripheral  devices 

Permanent  file 
Permanent  symbol 

Physical  device 
Physical  name 

PIC  code 

Pointer 


The  technique  of  repeatedly  using  the 
same  area  of  memory  during  different 
stages  of  a  program.  When  one  routine  is 
no  longer  needed  in  memory,  another  rou¬ 
tine  can  replace  all  or  part  of  it.  Over¬ 
laying  replaces  parts  of  programs;  chain¬ 
ing  replaces  the  whole  program. 

A  section  of  code  handled  as  a  unit.  This 
segment  of  code  can  overlay  code  already 
in  memory  or  be  overlaid  by  another  over¬ 
lay  segment. 

A  term  describing  a  program  which  does  not 
entirely  reside  in  high-speed  memory  at 
any  instant.  Portions  of  the  program  are 
brought  into  memory  when  needed. 

That  portion  of  a  file  delimited  by  form 
feed  characters,  generally  50-60  lines 
long;  corresponds  approximately  to  a 
physical  page  of  program  listing. 

A  variable  or  an  arbitrary  constant  appear¬ 
ing  in  a  mathematical  expression,  each 
value  of  which  restricts  or  determines 
the  specific  form  of  the  expression. 

To  modify  a  routine  in  a  rough  or  expedient 
way,  usually  by  modifying  the  binary  code 
rather  than  reassembling  it. 

In  a  data  processing  system,  any  device 
distinct  from  the  central  processing  unit, 
which  may  provide  the  system  with  outside 
storage  or  communication. 

An  output  file  that  is  stored  in  memory 
for  later  use. 

Instruction  mnemonics,  assembler  directives, 
and  macro  directives  incorporated  in  the 
assembler. 

An  input,  output,  or  storage  device  associa¬ 
ted  with  the  Central  Processing  Unit. 

A  2-  or  3-character  name  identifying  a 
physical  device.  The  first  two  characters 
are  alphabetic,  the  third  character  is 
numeric . 

Abbreviation  for  Position  Independent  Code. 
(Code  which  can  operate  properly  wherever 
it  may  be  loaded  in  memory) . 

1.  A  location  containing  the  address  to 
another  location. 

2.  In  EDIT  program,  a  moveable  reference 
pointer  normally  located  between  the 
character  most  recently  operated  upon 
and  the  next  character  in  the  buffer; 
represents  the  current  position  of  the 
Editor  in  the  text. 
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Proceed  count 

In  a  program  loop,  the  number  of  times 
the  breakpoint  is  to  be  encountered  before 
suspension  of  program  execution. 

Processor  status  register 

A  register  that  indicates  the  current 
priority  of  the  processor,  the  condition 
of  the  previous  operation,  and  other 
basic  control  items. 

Program  counter 

A  register  in  the  CPU  that  holds  the 
address  of  the  current  instruction  being 
executed  plus  two;  in  other  words,  it 
holds  the  address  of  the  next  instruction 
unless  the  current  instruction  causes  a 
jump. 

Program  sections 

see  Control  section 

Programmed  requests 

Machine  language  instruction  which  is  used 
to  invoke  a  monitor  service  for  the  issuing 
program. 

Purge 

Deactivate  a  channel,  without  taking  any 
other  action. 

Radix 

The  base  of  a  number  system,  the  number 
of  digit  symbols  required  by  a  number 
system. 

Real  time 

1.  Pertaining  to  the  actual  time  during 
which  a  physical  process  takes  place. 

2.  Pertaining  to  the  performance  of  com¬ 
puter  activity  which  occurs  fast 
enough  to  influence  the  related  physi¬ 
cal  process. 

Real  time  system 

A  system  in  which  computation  is  perfor¬ 
med  while  a  related  physical  process  is 
occurring  so  that  the  results  of  the  com¬ 
putation  can  be  used  in  guiding  the  physi¬ 
cal  process. 

Record 

A  collection  of  related  items  of  data 
treated  as  a  unit.  Example:  A  line  of 
source  code. 

Reentry  address 

The  Start  address  -2.  Allows  user  pro¬ 
gram  to  reset  itself  internally,  and  re¬ 
sume  operation. 

Region  number 

A  number  which  is  used  to  identify  a  por¬ 
tion  of  memory  to  the  Linker  for  the 
purpose  of  describing  an  overlay  struc¬ 
ture. 

Relocatable  code 

Code  written  so  that  it  can  be  located  and 
executed  in  any  part  of  memory,  once  it 
has  been  linked  by  Linker. 

Relocatable  object  modules 

A  set  of  instructions  which  are  written  so 
that  the  module  can  be  loaded  and  executed 
in  any  memory  area. 
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Relocatable  symbols 

Symbolic  names  whose  associated  value  is 
an  offset  from  the  base  (beginning)  of  a 
control  section.  Such  a  symbol's  value 
depends  on  the  address  of  the  control 
section  and  must  be  relocated  each  time 
the  control  section  is  assigned  an  address 
by  the  Linker. 

Relocation 

To  move  a  routine  from  one  portion  of 
storage  to  another  and  to  adjust  the 
necessary  address  references  so  that  the 
routine  can  be  executed  in  the  new  loca¬ 
tion. 

Relocation  directory 

A  portion  of  an  object  module  which  des¬ 
cribes  and  identifies  all  occurrences  of 
relocatable  symbols  in  the  object  module. 

Repeat  block 

Block  of  code  to  be  repeated  a  defined 
number  of  times. 

Repeat  count 

The  number  of  times  a  block  of  code  is 
to  be  repeated. 

Resident 

In  memory,  as  opposed  to  being  stored 
externally. 

Resident  monitor  (RMON) 

The  permanent  memory-resident  part  of 

RT-11.  Contains  console  terminal  service, 
the  error  processor,  the  system  device 
handler,  the  EMT  processor,  and  system 
tables . 

Root  segment 

See  Base  segment. 

Scratch  area 

Any  memory  or  registers  used  for  temporary 
storage  of  partial  results. 

Scrolling 

On  a  display  screen,  when  the  maximum 
number  of  lines  are  on  the  screen,  the 
top  line  is  deleted,  and  all  text  moves 
up  one  line,  permitting  one  new  line  of 
display  at  the  bottom  of  the  screen.  The 
visual  effect  is  similar  to  the  rolling 
up  of  a  scroll. 

Sentinel  file 

Last  file  on  cassette  tape?  contains  only 
header  record?  represents  logical  end-of- 
tape. 

Sequence  number 

The  number  in  a  cassette  directory  which 
designates  where  a  file  is  placed  (in 
sequence) ,  when  that  file  has  been  con¬ 
tinued  on  more  than  one  cassette. 

Sequential 

A  means  of  accessing  data,  in  which  records 
are  read  one  after  another  from  the  de¬ 
vice.  As  opposed  to  random  access. 

Software  mode 

For  magnetic  tapes  and  cassettes,  the  mode 
of  operation  when  device  access  is  through 
any  RT-11  system  program. 
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Source  code 

Text,  usually  in  the  form  of  an  ASCII  for¬ 
matted  file,  which  represents  a  program. 
Such  a  file  can  be  processed  by  an  approp¬ 
riate  system  program  (MACRO  or  FORTRAN) 
to  produce  an  object  module. 

Source  file 

A  file  to  be  used  as  input  to  a  translat¬ 
ing  program  such  as  MACRO  or  BASIC. 

Stack 

An  area  of  memory  set  aside  by  the  pro¬ 
grammer  for  temporary  storage  or  subroutine 
interrupt  service  linkage.  The  stack  uses 
the  "last-in,  first-out"  concept.  The 
stack  starts  at  the  highest  location  re¬ 
served  for  it  and  expands  linearly  down¬ 
ward  as  items  are  added  to  the  stack. 

Stack  pointer 

A  general  register  used  to  keep  track  of 
the  last  location  where  data  is  entered 
into  the  stack. 

Storage  device 

A  general  term  for  any  device  capable  of 
retaining  information. 

Subconditionals 

Directives  that  indicate: 

1.  assembly  of  an  alternate  body  of  code; 

2.  assembly  of  a  non-contiguous  body  of 
code  within  a  conditional  block; 

3 .  Unconditional  assembly  of  a  body  of 
code  within  a  conditional  block. 

Subpicture  address 

Address  of  a  set  of  display  processor 
instructions  which  display  text  on  a 

GT40  (42,44). 

Suspend 

To  temporarily  halt  execution  of  a  task 
while  another  task  of  different  priority 
runs . 

Swap 

The  movement  by  the  monitor  of  user  pro¬ 
grams  between  memory  while  they  are 
running  and  a  buffer  area  on  a  mass 
storage  device  when  something  else  is 
running  in  that  place  in  memory. 

Switch  register 

A  location  in  the  CPU  which  can  be  loaded 
with  a  value  by  the  operator,  by  his 
setting  switches  on  the  computer  console 
for  each  bit  he  wants  to  enter. 

Switches 

1.  In  a  command  string  to  the  CSI  a 
switch  is  a  slash  followed  by  an 

ASCII  character  which  can  be  given  a 
value  by  typing  a  colon  after  the 
character  followed  by  an  octal  number 
or  from  1-3  ASCII  characters. 

2.  Two  or  three  position  mechanisms  used 
for  operating  computers  or  devices. 
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Symbols 

Names  which  can  be  assigned  values  or 
which  can  be  used  to  indicate  specific 
locations  in  a  program. 

Symbol  table 

An  array  which  contains  all  defined  sym¬ 
bols  and  the  binary  value  associated  with 
each  one.  Mnemonic  operators,  labels  and 
user  defined  symbols  are  all  placed  in 
the  symbol  table.  (Mnemonic  operators 
stay  in  the  table  permanently.) 

System  configuration 

see  Configuration 

System  device 

A  peripheral  mass  storage  device  on  which 
the  Monitor  resides. 

System  programs 

DEC-supplied  programs  which  come  in  the 
basic  software  packages .  These  include 
editors,  PIP,  assemblers,  compilers, 
loaders ,  etc . 

Time-critical  job 

A  job  which  demands  response  within  a 
fixed  time  period. 

Transfer  address 

Program  entry  point. 

Trap 

An  automatic  transfer  of  control  to  a 
prespecified  routine  that  can  be  caused 
by  software  or  hardware.  The  trap  in¬ 
struction  is  an  example  of  a  hardware 
implementation . 

A  conditional  jump  to  a  known  location 
performed  automatically  by  hardware  as  a 
side  effect  to  executing  a  processor  in¬ 
struction.  The  address  location  from 
which  the  jump  is  made  is  recorded.  It 
is  distinguished  from  an  interrupt  which 
is  caused  by  an  external  event. 

Truncation 

The  reduction  of  precision  by  ignoring 
one  or  more  of  the  digits;  not  rounding 
off. 

Two's  complement 

A  number  used  to  represent  the  negative 
of  a  given  value  in  many  computers. 

This  number  is  formed  from  the  given  bin¬ 
ary  value  by  changing  all  Is  to  Os  and 
all  Os  to  Is,  and  then  adding  1. 

Type-ahead 

The  ability  to  type  information  at  the 
console  terminal  and  have  it  remembered 
by  the  system  for  later  use. 

Unary  operation 

Operation  affecting  a  single  operand. 
Examples:  negation,  radix  indicator. 

User-defined  symbol 

1.  A  label 

Utility 

2.  A  symbol  defined  by  direct  assignment. 

Any  program  which  performs  useful  functions, 
i.e.,  PIP. 
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Wild  card  operation 

Word-for-word  transfer 

Words 

Write-lock  condition 

Zero 


Two  words  describing  1)  where  to  go  when 
external  interrupt  occurs,  and  2)  the 
contents  of  the  processor  status  word  when 
the  interrupt  is  acknowledged. 

A  shorthand  method  of  transferring  all 
files  with  the  same  name,  extension,  or 
both. 

A  transfer  in  which  no  alteration  of 
data  is  performed. 

In  the  PDP-11  a  16-bit  unit  of  data  which 
may  be  stored  in  an  addressable  location. 

The  condition  of  a  device  that  is  pro¬ 
tected  against  any  transfers  which  would 
write  information  to  it. 

To  initialize  a  device  (e.g.,  DECtape, 
cassette)  so  that  it  contains  no  infor¬ 
mation. 
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Absolute,  5-3 

and  relocatable  program 
sections,  6-4 
block  numbers,  4-21,  1-2 
expression,  5-18,  C-5 
load  address,  6-1 
load  module,  6-5 
mode,  5-24 

quantities,  5-17 
section,  6-4 
starting  block,  4-17 
Absolute  Loader,  6-5,  A-8 
Accessing 

general  registers,  8-9 
internal  registers,  8-10 
Additional  reference  manuals,  xvi 
Address  mode  syntax,  C-5 
Address  specifier,  M-2 
Addressed  location,  8-8 
Addresses,  vector,  9-6 
Addressing  modes,  5-20 
Advance  command,  3-17 
Allocating , 

blocks  for  files,  4-11 
extra  words,  4-18 
memory  for  a  queue,  9-66 
system  resources,  2-16 
words,  2-35 

Alphabetize  switch,  6-18 
Alphabetized  load  map,  6-19 
Alphanumeric  representation,  1-2 
ALTMODE,  3-2 
Argument,  3-4 
block,  9-3 
CSECT ,  M-3 
dummy,  5-67 
iteration,  3-8 
list,  9-5 
list  pointer,  9-2 
negative  line,  3-7 
numeric,  3-6 
numerical,  9-4 
positive,  3-7 
substitution ,  5-72 
Arguments,  9-2 
EDIT,  3-4 

indefinite  repeat,  5-72 
missing,  5-66 
number  of,  5-66 
real,  5-63 
symbolic,  5-37 
to  Macro  calls  and 
definitions,  5-62 


ASCII, 

character  set,  C-l,  C-4 
conversion  of  one  or  two 
characters,  5-40 
files,  3-1 
format^  2-3 

input  and  output,  8-20 
.ASCII  directive,  5-41 
. ASCI Z  directive,  5-42 
.ASECT  directive,  5-53,  6-4,  6-6 
.ASECTs,  H-3 

ASEMBL  ( 8K  assembler),  1-4,  11-1 
assembling  and  linking,  A-18 
calling  and  using,  11-1 
error  messages,  11-6 
file  specifications,  11-2 
Assembler,  1-2,  8-4 
ASEMBL,  11-1 
MACRO,  5-1 
output,  5-19 

Assembler  directives,  5-3,  5-27,  C-19 
.ASCII,  5-41 
. ASCI Z ,  5-42 
.ASECT,  5-53 
. BLKB ,  5-47 
. BLKW,  5-47 
.BYTE,  5-38 
.CSECT,  5-53 
. DSABL ,  5-36 
. ENABL ,  5-36 
.END,  5-50 
. ENDM,  5-60 
.EOT,  5-51 
.ERROR,  5-70 
.EVEN,  5-46 
. FLT2 ,  5-48 
. FLT4 ,  5-48 
. GLOBL ,  5-54 
.IDENT,  5-36 
.IFF,  5-57 
. IFT ,  5-57 
. IFTF ,  5-57 
• IRP ,  5-71 
. I RPC ,  5-72 
.LIMIT,  5-51 
.LIST,  5-27 
.MACRO,  5-60 
. MCALL ,  5-74 
.MEXIT,  5-61 
.NARG,  5-68 
. NCHR,  5-68 
.NLIST,  5-27 
. NTYPE ,  5-69 
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.NTYPE,  5-69 
.ODD,  5-46 
.PAGE,  5-36 
.PRINT,  5-71 
.RADIX,  5-44 
. RAD  5  0 ,  5-43 
.REPT,  5-73 
. SBTTL ,  5-34 
.TITLE,  5-34 
.WORD,  5-39 

Assembly  and  Linking  Instructions, 
A- 14 

ASEMBL ,  A- 18 
CREF,  A- 18 
DUMP,  A- 20 
EDIT,  A- 17 
EXPAND,  A- 17 
FILEX,  A- 19 
LIBR,  A- 19 
LINK,  A- 18 
MACRO,  A- 17 
ODT ,  A- 21 
PATCH,  A- 20 
PIP,  A- 19 
SRCCOM,  A- 20 
the  system  files,  A-15 
the  VT-11  Display  Handler 
Library,  A- 21 

Assembling  graphics  programs,  N-16 
Assembly  instructions,  N-24 
Assembly, 

language  display  support,  N-l 
language  statement,  5-2 
link,  and  build  instructions,  A- 
listing,  8-1 

listing  table  of  contents,  5-35 
location  counter,  5-14 
pass,  5-14 

source  listing  showing  local 
symbol  blocks,  5-15 
ASSIGN  command,  2-18 
Asterisk,  wild-card,  4-1 
Asynchronous  completion  routines, 
9-13 

Autodecrement  mode,  5-23 
Autodecrement  deferred  mode,  5-23 
Autoincrement  mode,  5-21 
Autoincrement  deferred  mode,  5-22 
Automatic  generation  of  local 
symbols,  5-13 

Automatic  relocation  facility,  8-4 
Automatically  created  symbols 

within  user-defined  Macros,  5-66 

Backslash,  8-7 

Backup  storage  device,  6-10 

Back-arrow,  8-8 

Back  space,  H-ll 

Bad  block  files,  4-2 

Bad  block  scan,  4-21 

Bad  entry,  8-2,  8-26 

Base  address,  5-25,  8-4 


Base  command,  2-28 
Base  segment,  N-2 

BASIC/GT  subroutine  structure,  N-20 
BASIC/RT-11 ,  1-1,  1-5 
commands,  F-3 
error  messages,  F-6 
function  errors,  F-9 
functions,  F-5 
language,  F-l 
language  summary,  F-l 
statements,  F-l 
string  functions,  F-5 
Beginning  command,  3-16 
Binary, 

code,  1-2 

object  module,  8-4 
operators,  5-8,  5-18 
output,  1-2 
radix,  5-17,  5-45 
Bit  patterns,  1-3,  8-24 
search,  8-10 
.BLANK,  N-3 
Blank  COMMON,  6-14 
Blank, 

extension  filename,  2-7 
fields,  9-110 
lines,  5-2 

. BLKB  directive,  5-47 
. BLKW  directive,  5-47 
Blocks,  2-10 
control,  6-1 
device,  9-5 
EMT  arguments,  9-5 
lengths,  4-4 
2 56 -word,  2-31 
Block  numbers,  H-9 
absolute,  1-2 
physical,  1-2 

Block-replaceable  devices,  2-35, 
4-14 

BM792-YB  hardware  bootstrap,  2-1 
Boot  operation,  4-20 
Bootstrap, 

copy  operation,  4-20 
file,  4-19 

hardware  (cassette) ,  A-6 
loader,  A- 8 
manual,  2-2 

Bootstrapping  the  system,  4-20 
Bottom  address  switch,  6-18 
Branch, 

address,  5-26 

instruction  addressing,  5-26 
instructions,  5-27,  C-13 
Breakpoints,  8-11,  8-21 
table,  8-10,  8-13 
Buffer, 

flag,  N-7 ,  N-ll 
macro,  3-10 
save,  3-10 
structure,  N-7 
text,  3-2,  3-21 
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Building, 

a  memory  image,  2-28 
DECtape  from  DECtape,  A-2 
DECtape  from  Disk,  A-2 
Disk  from  DECtape,  A-2 
Disk  from  Disk,  A-2 
Disk  from  Cassette,  A-6 
Disk  from  Paper  Tape,  A-8 
RT-11  systems,  A-l 
VTLIB . OBJ ,  N-26 
Byte,  8-7 

offset,  5-27 
BYTE  command ,  M- 3 
.BYTE  directive,  5-38 


Calculating  offsets,  8-17 
Calling  and  using, 

ASEMBL ,  11-1 
DUMP,  1-1 
EDIT,  3-1 
EXPAND,  10-2 
FILEX,  J-l 
LIBR,  7-1 
LINK,  6-2 
MACRO,  5-74 
ODT ,  8-1 
PATCH,  L-l 
PATCHO,  M-l 
PIP,  4-1 
SRCCOM ,  K-l 

Calls  or  branches  to  overlay 
segments,  6-13 
Card  codes,  2-24,  H-6 
conversion  table,  H-25 
Card  reader  handler,  H-6 
Carry  bit,  9-13 
Cassette, 

rewind  button,  4-7 
sequence  number,  4-7 
Cassette  special  functions,  H-12 
last  block,  H-12 
last  file,  H-12 
next  block,  H-12 
next  file,  H-12 
rewind,  H-12 
write  file  gap,  H-13 
Cassettes  and  magtapes, 
initializing,  4-13 
legal  operations,  4-5 
Cathode  ray  tube,  N-l 
CBOOT ,  A-6 

instructions,  A-7 
CBUILD • SYS ,  A-6 
. CDFN  request,  9-25 
Centralized  queue  management 
system,  9-65 
CHAIN  bit,  9-8 
.CHAIN  request,  9-27 
Change  command,  3-22 


Changing 

device  handler  characteristics, 
2-23 

stack  size,  2-35 
Channel,  9-41 
data,  9-78 
number,  9-5 

status  word,  9-13,  9-41,  9-78 
Channels,  9-35 
Character 

deletion,  9-94 
substitution ,  5-72 
transfer,  9-93 
Character  set,  5-5 
ASCII,  C-4 
Radix-50,  C-3 

Character-  and  line-oriented 
command  properties,  3-6 
Character-oriented  commands,  3-6 
Characters , 
filler.  A- 11 
illegal,  5-7 
legal,  5-5 
operator,  5-8 
optional,  2-14 
prompting,  2-4 
special,  5-64 
• CHCOPY  request,  9-28 
Checking  channel  status,  9-99 
Checksum,  4-9,  M-4,  M-5 
.CLEAR,  N-4 

Clearing  breakpoints,  restarting 
ODT,  8-2 
Clock,  2-17 

frequency,  9-52 
ticks,  9-51 
CLOSE  command,  2-20 
CLOSE  handler  function,  H-9 
.CLOSE  request,  9-30 
Closed  location,  8-6 
. CMKT  request,  9^31 
• CNTXSW  request ,  9-32 
Code , 

binary,  1-2 
modifications ,  L-l 
object,  1-2 
source,  1-2 
Combining 
files,  4-9 

library  switch  functions,  7-11 
Command  and  Switch  Summaries,  B-l 
Command, 

arguments  (EDIT),  3-5,  B-5 
continuation  switch,  7-3 
decoder,  8-20 
execution  routine,  8-20 
interpretation  services,  9-1 
mode,  3-2 
repetition,  3-8 
string  format,  2-10 
strings,  3-5,  6-2 
structure  (EDIT) ,  3-3 
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switches,  4-1,  K-2 
syntax  (LIBR) ,  7-2 
Command  String  Interpreter 
2-10,  6-3,  9-33,  L-2 
Command  summary, 

ODT ,  B-12 
PATCH,  B-16 
PATCHO,  B-17 
Commands , 

and  functions,  8-5 
BASIC/RT-11 ,  F-3 
character-oriented,  3-6 
control,  3-2 
display  editor,  3-4 
edit  control,  3-2 
editing,  3-10 
input/output,  3-3,  3-10 
keyboard,  2-14 
line-oriented,  3-6 
PATCH,  L-2 

pointer  relocation,  3-16 
search,  3-18 
text  modification,  3-4,  3-20 
utility,  3-4,  3-24 
Commands  to  allocate  system 
resources,  2-16 
ASSIGN,  2-18 
CLOSE,  2-20 
DATE,  2-16 
INITIALIZE,  2-18 
LOAD,  2-20 
SET,  2-23 
TIME,  2-17 
UNLOAD,  2-23 

Commands  to  control  terminal  I/O, 
2-15 

GT  OFF,  2-16 
GT  ON,  2-15 

Commands  to  manipulate  memory 
images,  2-27 
Base,  2-27  ~ 

Deposit,  2-29© 

Examine,  2-29 
GET,  2-27 
SAVE,  2-30 

Commands  used  only  in  a  F/B 
environment,  2-34 
FRUN,  2-35 
RSUME ,  2-37 
SUSPEND,  2-36 
Command  field,  5-2,  5-4 
Common  blocks,  6-14 
Compiling  and  linking  PATCHO,  A-20 
Completion  functions,  9-14 
Completion  routines,  2-36,  2-37, 
9-13,  9-49,  9-60 
Component  sizes,  2-9 
Components , 

system  hardware,  1-5 
system  software,  1-3 
Compress  operation,  4-19 


Compressing 

directories,  4-19 
files,  4-19 
Concatenation ,  5-67 
Condition  codes,  8-10 
Conditional , 

assembly  directives,  5-55 
block,  5-55 

Configuration  word,  9-11,  9-52,  9-85 
Confirming  file  transfers,  4-10 
Console , 

normal  mode,  9-94 
special  mode,  9-94 
terminal,  3-1,  3-27 
terminal  control  and  status 
registers,  9-12 

Constant  register,  8-5,  8-10,  8-16 
Context  switch,  9-32 
Contiguous , 
area,  9-13 

file,  7-12,  9-13,  J-7 
Continuation  lines,  5-2 
Continue  switch,  6-20 
Control, 
block,  6-1 
commands,  3-2 
parameters,  6-6 
section  names,  6-1 
Control  section, 
named,  6-4 
unamed,  6-4 

Controlling  terminal  I/O,  2-15 
Conventions,  system,  2-3 
Converting  VI  Macro  calls  to  V2, 
9-108 

Copy  operations,  4-9 
errors,  4-9 
multiple,  4-11 
Copying, 

files  with  the  current  data,  4-10 
system  files,  4-10 
Co-resident  overlay  routines,  6-22 
Core  memory,  1-1 

Correct  and  incorrect  macro  calls, 
9-3 

Correcting  and  updating  object 
modules,  M-l 
CR  (card  reader) ,  H-6 
Creating, 

a  library  file,  7-4 
a  new  file,  4-6 
CREF,  1-4 

assembling  and  linking,  A-18 
error  messages,  5-86 
listing  output,  5-81,  5-82,  5-83 
specification  switches,  5-76 
switches,  5-78,  C-24 
Cross  reference, 

control  sections,  5-78 
errors,  5-78 
listings,  1-4 
MACRO  symbols,  5-78 
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permanent  symbols,  5-78 
register-equate  symbols,  5-78 
table  generation,  5-78 
CR.SYS,  A- 3 
CSECT  argument,  M-3 
• CSECT  directive,  5-53,  6-4 
CSECT,  7-13 
CSI, 

error  messages,  9-35 
general  mode,  9-34 
special  mode,  9-36 
switch  separators,  9-38 
. CSIGEN  request,  9-33 
. CSISPC  request,  9-36 
. CSTAT  request,  9-41 


CTRL 

A, 

2-12 

CTRL 

B, 

2-12 

CTRL 

c, 

2-12, 

3-2, 

8-3 

CTRL 

E, 

2-12 

CTRL 

F, 

2-12 

CTRL 

0, 

2-13, 

3-3, 

H-5 

CTRL 

Q, 

2-13 

CTRL 

s  r 

2-13 

CTRL 

u. 

2-13, 

3-3, 

CO 

CTRL 

x, 

3-3 

CTRL 

z, 

2-13, 

H-5 

CT.SYS, 

A- 3 

Current 

f 

location  counter,  5-3,  5-14 
location  pointer,  3-6 
subpicture  tag,  N-14 
Cursor,  3-28,  N-2 

Customization  for  special  hardware 
A- 11 


Data, 

format,  2-3,  J-l 
length,  9-78 

storage  directives,  5-37 
transfer  requests,  9-15 
DATE  command,  2-16 
.DATE  request,  9-20 
De-activating  a  channel,  9-65 
Debugger,  1-2 
Debugging, 
process,  1-2 
tool,  1-3 
DEC  command,  M-4 

DEC  026/029  card  conversion  table, 
H-25 

Decimal , 

number,  5-17 
radix,  5-17,  5-45 
DECsystem-10, 

DECtape,  J-l 

file-structured  device,  J-3 
DECtape, 

DECsystem-10,  J-l 
PDP-11  DOS/BATCH,  J-l 
RSTS-11 ,  J-l 


Default, 

extensions,  9-34 

FORTRAN  library  switch,  6-20 

stack,  9-7 

Defining  NOTAG,  N-19 
Delete 

command,  3-21 
global  switch,  7-7 
operation,  4-13 
switch,  7-6 

DELETE  handler  function,  H-8 
.DELETE  request,  9-42 
Deleted  files, 
on  cassette,  4-6 
on  magtape,  4-6 
Deleting  files,  4-13 

from  DOS/BATCH  (RSTS-11)  DECtapes , 
J-7 

Delimiting  characters,  3-25 
separating  and,  5-6 
Deposit  command,  2-29 
Description  of  graphics  macros,  N-3 
Destination  device,  4-9 
Device , 

block,  9-5 
designation,  3-12 
file- formatted,  J-l 
name,  logical,  2-5 
name,  physical,  2-19,  9-5 
non-file  structured,  6-21 
ownership,  2-21 
random  access,  4-8,  6-1 
r  size,  9-46 

specification,  2-11 
Device  Handlers,  2-8,  9-50,  H-4 
differences  between  VI  and  V2 , 

H-4 

foreground  programming  and,  H-l 
loading,  9-50 
user-written,  H-4 

Device-independent  functions,  9-85 
Device  names, 
logical,  2-5 
permanent,  2-5 
physical,  2-4 
.DEVICE  request,  9-44 
DHALT  display  halt  instruction,  N-14 
Differences  between  VI  and  V2 
device  handlers,  H-4 
entry  conditions,  H-4 
header  words,  H-4 
interrupt  handling,  H-4 
Differences  between  VI  and  V2  RT-11, 
xv 

Direct  assignment  statement,  5-10, 
5-14 

conventions,  5-11 
format,  5-10 
Directives , 

assembler,  see  assembler  directives 
conditional  assembly,  5-55 
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data  storage,  5-37 
immediate  conditional,  5-58 
listing  control,  5-27 
Macro,  5-60 

not  available  in  ASEMBL,  11-2 
PAL- HR,  5-59 
PAL-11S ,  5-59 
program  boundaries,  5-51 
program  section,  5-51 
terminating,  5-50 
Directory, 

access  motion  and  code  consoli¬ 
dation,  9-79 
blocks,  4-19 

initialization  operation,  4-18 
list  operations,  4-15 
listings  of  magtapes,  4-7 
segments,  4-18 

Directories,  compressing,  4-19 
Disk,  DOS/BATCH,  J-l 
Display, 

extended  instructions,  N-13 
file  handler,  N-l,  N-2 
file  structure,  N-17 
handler  macro  calls,  N-16 
hardware,  3-29 
interrupt  vectors,  N-5 
processor,  N-l 
program  counter,  N-14 
screen,  3-27 
status  register,  N-14 
status  words,  N-8 
stop  instruction,  N-2,  N-18 
stop  interrupt  handler,  N-14 
X  register,  N-14 
Y  register,  N-14 
Display  editor,  3-27 
format,  3-28 
using  the,  3-28 
Display  processor,  N-l 
management,  N-2 
mnemonics,  N-16,  N-23 
DJSR  subroutine  call  instruction, 
N-13 

DNAME  load  name  register  instruc¬ 
tion,  N-15 
DOS/BATCH  disk,  J-l 
Double  ALTMODE,  3-28 
Double-buffered  I/O,  9-105 
Double  Operand  Instructions,  C-8 
Double  Register-Destination,  C-17 
DRET  subroutine  return  instruc¬ 
tion,  N-14 

. DSABL  directive,  5-36 
DSTAT  display  status  instruction, 
N-14 

. DSTATUS  request,  9-45 
DTMNFB . SYS ,  A- 2 
DTMNSJ • SYS ,  A- 2 
DT.SYS,  A- 3 


Dummy, 

argument,  5-67 
argument  list,  5-60 
file,  4-6 
names,  4-14 
DUMP,  1-5,  1-1 

assembling  and  linking,  A-20 
calling  and  using,  1-1 
error  messages,  1-5 
switches,  1-2,  B-14 
DUMP  command,  M-4 
Duplicate  entry  points,  7-8 


E  command,  L-3 
EC  command,  3-29 
Edge  flag,  N-12 
Edit  Backup  command,  3-11 
Edit  Console  command,  3-29 
Edit  Display  command,  3-29 
Edit  Read  command,  3-10 
Edit  Version  command,  3-27 
Edit  Write  command,  3-11 
Editor  (EDIT),  1-2,  3-1 
arguments,  '3-4,  3-5,  B-5 
assembling  and  linking,  A-17 
calling  and  using,  3-1 
command  structure,  3-3 
control  commands,  3-2 
display,  3-27 
editing  commands,  3-10 
error  messages,  3-33 
example,  3-32 

immediate  mode  commands,  3-30, B-8 
input/output  commands,  3-10,  B-5 
key  commands,  3-2,  B-8 
modes  of  operation,  3-2 
pointer  relocation  commands,  3-16, 
B-6 

search  commands,  3-18,  B-6 
text  modification,  3-20 
utility  commands,  3-24,  B-7 
Effective  address  search,  8-15 
Empty  entry,  9-13,  9-43 
EMT, 

and  TRAP  addressing,  5-27 
argument  blocks,  9-5 
error  code,  9-8 
instruction,  9-2 
. ENABL  directive,  5-36 
.END  directive,  5-50 
End  File  command,  3-15 
. ENDM  directive,  5-60 
. ENDM  statement,  5-74 
.ENDR  statement,  5-74 
ENTER  handler  function,  H-8 
.ENTER  request,  9-47 
Entering  I/O  information,  2-10 
Entry  conditions,  H-4 
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Entry  point,  5-10,  5-55,  6-7, 

6-13,  9-46 

table,  7-5,  7-12,  7-13 
Entry  symbol,  6-5 
.EOT  directive,  5-51 
Error, 

code,  9-35 
returns,  9-99 
types,  P-1 

.ERROR  directive,  5-70 
Error  halt  bit,  9-8 
Error  messages, 

ASEMBL ,  11-6 
BASIC/RT-11 ,  F-6 
CREF,  5-86 
DUMP,  1-5 
EDIT,  3-33 
fatal  monitor,  2-38 
keyboard,  9-40 
MACRO,  5-84 
monitor,  2-37 
PATCH,  L-7 
PATCHO,  M-7 
PIP,  4-24 
summary,  P-1 

Evaluation  of  an  expression,  5-18 
Even  byte,  9-6 
.EVEN  directive,  5-46 
Examine,  change  locations  in  the 
file,  L-3 

Examine  command,  2-29 
Examples , 

device  handlers,  H-14 
EDIT,  3-32 

MACRO  line  printer  listing,  5-31 
page  heading,  5-32 
PATCH,  L-4 
PATCHO,  M-5 
using  GTON ,  N-28 
EX  command,  3-16 
Exchange  command,  3-23 
Execute  Macro  command,  3-26 
Exit  command,  3-15 
EXIT  command,  M-4 
Exit  from  PATCH,  L-3 
.EXIT  request,  9-49 
EXPAND,  1-4,  10-1 

assembling  and  linking,  A-17 
calling  and  using,  10-2 
error  messages,  10-6 
language,  10-1 
restrictions ,  10-1 


Expression, 

C-5 

absolute , 

5-18, 

C-5 

external , 

5-18 

register. 

5-20, 

C-5 

relocatable,  5- 

18, 

Expressions 

,  5-18 

symbols  and,  5-5 
Extend  and  delete  operations, 
4-13 

Extended  display  instructions, 
N-13 


Extending  file  lengths,  4-13 
Extensions,  3-12,  K-2 
and  filenames,  2-5 
External, 

expression,  5-18 
symbols,  5-10,  6-5 


F  command,  L-2 
Facilities , 

available  only  in  RT-11  F/B,  1-7 
for  input  and  output  operations, 
9-1 

Fast  listing,  J-7 

Fatal  monitor  error  messages,  2-38 
F/B  Monitor,  9-7 

F/B  programming  and  device  handlers 
H-l 

F/B  programming  in  RT-11, 

Version  2,  H-l 

F/B  system,  background  area,  2-9 

.FETCH  request,  9-50 

Field, 

comment,  5-2,  5-4 
label,  5-2,  5-3 
operand,  5-4 
File, 

allocation  scheme,  4-10 
ASCII,  3-1 

descriptor  blocks,  9-37 
dummy,  4-6 
formats,  J-l 
gap,  9-86,  H-ll 
length,  9-78 

manipulation  requests,  9-15 
manipulation  services,  9-1 
memory  image,  2-3,  4-9,  L-l 
names  and  extensions,  2-5 
non-overlay,  L-3 
overlay,  L-l 
permanent,  9-13 
relocatable  image,  2-3 
replacement,  4-8 
sentinel,  4-4 

specifications  (ASEMBL) ,  11-2 
structure,  9-13,  H-6 
temporary,  4-23 
tentative,  9-13 
transfer,  4-1 

File-formatted  devices,  J-l 
File-structured  RT-11  device,  J-l 
Filename,  3-12 

blank  extensions,  2-7 
extensions,  2-6 
input,  4-1 
output,  4-1 

Files,  compressing,  4-19 
FILEX,  1-4,  J-l 

assembling  and  linking,  A-19 
calling  and  using,  J-l 
error  messages,  J-8 
overview,  J-l 
switch  options,  J-2,  B-15 
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Fill  characters,  2-31,  9-9,  A-ll 
Fill  count,  9-9 
Find  command,  3-19 
Fixed  record  length,  H-6 
Floating  point, 
exception,  9-84 
hardware,  5-47,  9-84 
numbers,  5-17,  5-48 
source  double  register,  C-15 
. FLT2  directive,  5-4.8 
. FLT4  directive,  5-48 
Foreground/Background,  1-1 
terminal  I/O,  2-13 
Foreground  links,  6-6 
Format , 

ASCII,  2-3 
control,  5-5 

load  image,  2-3,  6-2,  6-21 
memory  image,  2-3 
object,  2-3 

of  Entry  Point  Table,  7-13 
of  library  files,  7-12 
of  programmed  requests,  9-2 
relocatable  image,  2-3 
register,  8-6 
statement,  5-2 
Formats,  data,  2-3 
Formatted  binary  copy  switch,  4-9 
Formatting, 

horizontal,  5-5 
vertical,  5-5 

Form  feed  character,  3-1,  3-12 
Forms  of  relocatable  expressions, 
8-5 

FORTRAN  IV,  1-1,  1-5,  G-l 
character  set,  G-2 
compiler  error  diagnostics,  G-ll 
expression  operators,  G-3 
object  time  error  diagnostics, 
G-ll 

overlays,  G-14 

running  a  FORTRAN  program  in  the 
foreground,  G-l 
statements,  G-4 
Forward  space,  H-ll 
Fragmented  device,  9-13 
Free  area,  4-11 
Free  memory  list,  2-9,  2-22 
FRUN  command,  2-35 
FRUN  processor,  9-7 
Function, 
code,  9-6 

control  switches,  C-23 
switches,  5-76,  5-77 
Functions,  BASIC/RT-11,  F-5 


General , 

address  specification,  5-21 
file  transfer  program,  J-l 
library  file  format,  7-12 
memory  layout,  2-8 
registers,  5-11,  8-9. 


GET  command,  2-27 
Get  command,  3-18 
Global  symbol  directory,  7-14 
Global  symbol  table,  6-1,  6-5 
Global  symbols,  5-10,  5-55,  6-1, 
6-5,  M-3 

Globals,  unresolved,  6-1 
. GLOBL  directive,  5-54 
Graphics  macro  calls,  summary,  N-21 
Graphics  programs, 

assembling  and  linking,  N-16 
GT  OFF,  1-5,  2-15,  2-16,  N-2 
GT  ON,  1-5,  2-15,  3-29,  N-2 
. GTIM  request,  9-51 
. GTJB  request,  9-52 


HALT  instructions,  2-40 
Handler  functions,  H-8 
CLOSE,  H-9 
DELETE,  H-8 
ENTER,  H-8 
LOOKUP,  H-8 
READ /WRITE,  H-9 
Handler  size,  9-46 
Handlers,  2-35 
device,  2-8,  H-l 
display  file,  N-2 
internal  display  file,  N-2 
removing  from  memory,  9-74 
system,  A-l 

Hardware  bootstrap,  4-20 
BM792-YB,  2-1 
cassette,  A-6 
MR11-DB ,  2-2 
Hardware , 

configuration ,  2-1 
display,  3-29 
memory  protection,  9-6 
mode,  H-6 
Header  words,  H-4 
HELP  command,  M-5 
.HERR  request,  9-53 
High, 

address,  2-31 

baud  rate  serial  console  devices, 
A-ll 

level  languages,  1-3 
memory  address,  9-8 
order  time  of  day,  9-52 
Horizontal  formatting,  5-5 
.HRESET  request,  9-55 


Identification  messages,  2-3 
.IFF  Directive,  5-57 
. IFT  Directive,  5-57 
. IFTF  Directive,  5-57 
Illegal  characters,  5-7,  8-26 
Immediate  conditional  directive, 
5-58 
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Immediate  mode,  1-3,  3-2,  3-4, 
3-30,  5-24,  9-3 
commands,  3-30,  B-8 
Important  memory  areas,  9-6 
Improving  assembler  performance, 
A- 14 

Include  switch,  6-20 
Inclusive  directory,  4-5 
Indefinite  repeat 
arguments,  5-72 
block,  5-71,  5-72 
.IDENT  directive,  5-36 
Index  Mode,  5-23,  5-25 
Index  Deferred  Mode,  5-23 
Individual  module  name,  7-2 
Inhibit  TT  wait  bit,  9-8 
INITIALIZE  command,  2-18,  3-30 
Initializing  cassettes  and 
magtapes,  4-13 
Input  and  output,  3-3,  6-5 
commands  (Editor),  3-10,  B-5 
Input, 

filenames,  4-1 
list,  2-11 
ring  buffer,  H-5 
source  filename,  1-1 
Insert  command,  3-20 
Inserting  modules  into  a  library, 
7-5 

• INSRT ,  N-5 
Instruction, 

EMT,  9-2 
mnemonic,  5-3 
offset,  8-17 
Instructions,  C-6 
branch,  C-13 
double  operand,  C-8 
operate,  C-ll 
rotate/shift,  C-9 
single  operand,  C-8 
trap,  C-12 

.INTEN  request,  9-21,  H-4 
Internal 

buffers,  3-1 
Macro  buffer,  3-26 
registers,  8-10 
subpicture  stack,  N-14 
symbol  directory,  7-14 
symbolic  names,  5-53 
symbols,  5-10 
tables,  10-1 
Interrupt 

enable  bit,  9-44 
handling,  H-4,  N-2 
level  (issuing  programmed 
requests),  H-2 
priorities,  H-l 
priority  level,  8-10 
Service  Routine,  H-2,  H-3 
vector,  H-l,  H-3 
Invalid  punch  combinations, 

H-6 


I/O  count,  9-78 

exit  routine,  9-11 
vector,  9-33 

. IRP  and  .  IRPC  example,  5-73 
• IRP  directive,  5-71 
.IRPC  directive,  5-72 
Issuing  programmed  requests  at  the 
interrupt  level,  H-2 
Iteration  argument,  3-8 
loops,  3-9 


Job  Status  Word,  2-31,  2-34,  9-7, 
9-94 

Jump  command,  3-17 
Jumps,  6-13 


Key  commands.  Editor,  3-2,  B-8 
Key,  LINE  FEED,  8-7 
Keyboard, 

commands,  2-14 
communication  (KMON) ,  2-11 
error  messages,  9-40 
monitor  (KMON) ,  2-7 
Keyboard  Monitor  (KMON) ,  2-7 
command  summary,  B-l 
special  function  keys,  B-3 
Kill  command,  3-22 


Label  field,  5-2,  5-3 
Language  summary,  BASIC/RT-11,  F-l 
Last  block,  H-12 
Last  file,  H-12 
LDA  format,  6-2 
switch,  6-21 
Legal 

argument  delimiters,  5-63 
characters,  5-5 
operations  involving  cassette 
or  magtape,  4-5 

separating  characters,  5-6,  5-67 
wild  card,  4-2 

Librarian  (LIBR) ,  1-2,  1-3,  1-4,  7-1 
assembling  and  linking,  A-19 
calling  and  using,  7-1 
error  messages,  7-14 
switch  commands,  7-2,  7-3,  B-12 
Library 

directory,  7-1 
end  trailer,  7-14 
header,  7-1,  7-12,  7-13 
processing,  7-14 
searches,  6-17 
Library  files,  6-8 
creation,  7-4 
directory  listing,  7-9 
entry  point  table,  7-7 
format,  7-12 

inserting  modules  into,  7-5 
merging,  7-10 
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Light  pen,  N-l 

status  buffer,  N-ll 
.LIMIT  directive,  5-51 
Limitations,  PATCHO,  M-5 
Line-  and  character-oriented 
command  properties,  3-6 
line  deletion,  9-94 
formatting,  5-5 
oriented  commands,  3-6 
printer  overstriking  capability, 

2-23 

LINE  FEED  key,  8-7 

Linker  (LINK),  1-2,  1-4,  6-1,  7-14 
assembling  and  linking,  A-18 
calling  and  using,  6-2 
error  handling  and  messages , 6-24 
input  and  output,  6-5 
load  map,  8-2 

load  map  for  background  job, 

6- 9 

switches,  6-3,  B-ll 
Linked 

list,  9-66 
program,  6-1 

Linking  graphics  programs,  N-16 
Linking,  relocation  and,  5-19 
List  command,  3-14 
LIST  command,  M-4 
.LIST  directive,  5-27 
Listing, 

assembly,  8-1 

control  directives,  5-27 

control  switches,  5-76,  C-23 

cross-reference ,  1-4 

directories,  J-6 

level  count,  5-28 

the  directory  of  a  library  file, 

7- 9 

. LNKRT ,  N-5 
Load  address,  2-35 
absolute,  6-1 
LOAD  command,  2-20 
Load  image  format  ( . LDA) ,  2-3 
Load 

map,  1-2,  6-1,  6-7 
module,  1-2,  6-1,  6-5,  6-21 
Loader, 

absolute,  A-8 
bootstrap,  A-8 
Loading 

device  handlers,  9-50 
device  registers,  9-44 
memory  image  files,  2-32 
ODT  with  user  program,  8-2 
root  segment,  2-28 
Local  symbol  block,  5-13 
Local  symbols,  5-12,  5-66 
automatic  generation,  5-13 
Location, 

addressed,  8-8 
closed,  8-6 
counter  control,  5-46 
open,  8-6 


Locations,  opening,  changing,  and 
closing,  8-6 
.LOCK  request,  9-56 
Locking  USR  in  memory,  9-56 
Logical  device  name,  2-5 
end-of-tape,  4-5 
identifier,  9-5 
names,  2-5,  2-18 
LOOKUP  handler  function,  H-8 
.LOOKUP  request,  9-58 
Lowering  the  processor  priority, 
H-2 

Low  and  high  addresses,  5-51 
-order  priority,  8-19 
priority,  8-19 
. LPEN ,  N-7 
LP.SYS,  A- 3 
L-shaped  cursor,  3-28 
LSRA  instruction,  N-14 


Machine  language,  1-2 
Macro, 

arguments,  5-7 
buffer,  3-10 
call,  5-3,  9-2 
call  operator,  5-3 
defintion,  5-60 
definition  formatting,  5-61 
expansion,  9-24 
free  source  code,  10-1 
libraries,  5-74 
nesting,  5-63 
recursive,  10-6 
references,  10-1 
Macro  assembler,  1-1,  1-3,  5-1 
assembling  and  linking,  A-17 
calling  and  using,  5-74 
character  code,  C-l 
directives,  5-60 
error  messages,  5-84 
features,  5-1 
instructions,  C-l 

program  section  capabilities,  5-10 
source  code,  5-80,  5-81 
source  statements,  5-2 
special  characters,  C-5 
switches,  5-76,  C-23 
symbol  table,  5-9 
symbols,  5-9 
Macro  calls, 

requiring  no  conversion,  9-108 
which  may  be  converted,  9-108 
Macro  command,  3-10,  3-25 
.MACRO  directive,  5-60 
Magtape,  7-track,  A-ll 
Magtape  special  functions,  H-10 
back  space,  H-ll 
forward  space,  H-ll 
off  line,  H-12 
rewind,  H-10 
write  end-of-file,  H-ll 
write  with  extended  gap,  H-ll 
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Main  file/subroutine  structure, 
N-19 

Main  line  code,  H-5 
Mainstream  code,  9-87 
Making  patches  permanent,  2-27 
Manipulating  memory  images,  2-27 
Manual  bootstraps,  2-2 
Mark  time,  1-7 
requests,  9-31 
Mask  limit,  8-15 
Masking,  8-10 
Matching  areas,  K-l 
Maximum  file  size,  9-12 
. MCALL  directives,  5-74 
Memory  block  initialization,  8-16 
Memory 

core,  1-1 

diagram,  BASIC  link  with  overlay 
regions,  6-11 
maps,  2-8,  8-4 
solid  state,  1-1 
usage,  3-9 
usage  map,  6-6 
Memory  image,  L-l 

files,  2-3,  4-9,  L-l 
format,  2-3 

Merging  library  files,  7-10 
.MEXIT  directive,  5-61 
Minimum  memory  configurations,  5-1 
Miscellaneous  services,  9-16 
Missing  arguments,  5-66 
Mnemonics,  1-2 
Mode , 

absolute,  5-24 
autodecrement ,  5-23 
autodecrement  deferred,  5-23 
autoincrement,  5-21 
autoincrement  deferred,  5-22 
command,  3-2 
dump.  A- 11 
general,  9-34 
hardware,  H-6 

immediate,  1-3,  3-2,  3-4,  3-30, 
5-24 

index,  5-23,  5-25 
index  deferred,  5-23 
instruction,  8-17 
non- dump.  A- 11 
Radix-50,  8-10 
register,  5-21 
register  deferred,  5-21 
relative,  5-24 
relative  branch,  8-9 
relative  deferred,  5-25 
single  instruction,  8-14,  8-17 
software,  H-6 
source  operand,  5-25 
special,  9-36 
text,  3-2,  3-20 
type-ahead,  2-14 
Modes,  addressing,  5-20 
of  operation  (EDIT) ,  3-2 


Modify  stack  address,  6-21 
Modules,  1-2,  6-5 
absolute  load,  6-5 
load,  6-1,  6-5,  6-21,  7-1 
object,  6-5,  6-16,  7-1,  7-13,  7-14 
Monitor,  1-1,  2-1 

error  messages,  2-37 
F/B,  1-6,  9-7 
HALTS,  2-40 
keyboard  (KMON) ,  2-7 
memory  protection  map,  6-6 
Resident  (RMON) ,  2-7,  9-7 
running  version,  A-l 
single-job,  1-6,  3-30,  9-7 
software  components,  2-7 
start  procedure,  2-1 
version  number,  9-11 
MONITR. SYS ,  A-l,  A-2 ,  A-6 
MOV  instruction,  9-3 
MR11-DB  hardware  bootstrap,  2-2 
. MRKT  request,  9-60 
MT/CT  (Magtape  (TU10/TM11)  and 
Cassette  (TAll) ) ,  H-6 
general  characteristics,  H-6 
MT.SYS,  A- 3 
Multiple, 

command  lines,  2-14 
copy  operations,  4-11 
delimiters,  5-4 
GETS,  2-28 
labels,  5-3 
operands,  5-4,  5-38 
. QSET  requests,  9-66 
Multiply-defined  symbols,  5-13 
. MWAIT  request,  9-62 


[n]  construction,  4-11 
.NAME,  N-9 
Name  register, 
contents,  N-14 

internal  software  register,  N-15 
.NAME  request,  N-9 
Name  value,  N-7 
Named 

COMMON,  6-14 
control  sections,  6-4 
relocatable  program  sections, 
5-53,  5-54 

.NARG  directive,  5-68 
. NCHR  directive,  5-68 
Negative , 

line  arguments,  3-7 
numbers,  5-17 
Nesting  level,  5 
Next  —  - 

block,  H-12 
file,  H-12 
Next  command,  3-14 
. NLIST ,  5-27 
Non-dump  mode,  A-ll 
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Non-file  structured, 
delete,  4-5 
devices,  6-21 
lookup,  H-6 
Non-overlay  file,  L-3 
Non-time-critical  job,  1-7 
Nonexistent  symbol,  6-21 
. NTYPE  directive,  5-69 
Null  specification,  11-2 
Number,  C-18 
channel,  9-5 
decimal,  5-17 
monitor  version,  9-11 
of  arguments,  5-66 
update,  9-11 
Numbers , 

floating-point,  5-17,  5-48 
MACRO  assembler,  5-17 
negative,  5-17 
octal,  5-17 
positive,  5-17 

software  identification,  xiv 
Numeric  arguments,  3-6,  9-4 
passed  as  symbols,  5-64 
Numeric  control,  5-47 


Object 

code,  1-2 
files,  6-5 
format,  2-3 

modules,  5-19,  6-5,  6-16,  7-1, 

7- 13,  7-14,  A- 8 
modules,  relocatable,  8-1 
modules,  starting  point,  7-13 
output,  1-2 

.OBJ  format,  M-l 
Octal , 

channel  number,  9-13 
numbers,  5-17 
radix,  5-17,  5-45 
.ODD  directive,  5-46 
Odd  (high-order)  byte,  9-6 
ODT 

(On-line  debugging  technique) , 
1-5 

break  routine,  8-23 
command  summary,  B-12^ 
error  detection,  8-25 
functional  organization,  8-20 
priority  bit,  8-2 
p.  I'vity  level,  8-19 
*UT/T 

0  assembling.  a-2 1 
*****  calling  ‘ng,  8-1 

linkirgv  fjh  with  the  user 
urogram,  8-2 
Offline,  H-12 
Offset,  5-13,  5-25 
relative  branch,  8-9 
relative  branch  instruction, 

8- 17 
V- 


Offset  words,  9-11 
OLDPIP,  A- 9 

On-line  debugging  techniques  (ODT) 
-  see  ODT 
OPEN  command,  M-l 
Open  file,  2-20 
Opening  a  byte  address,  L-3 
Opening,  changing,  and  closing 
locations,  8-6 
Operand  field,  5-4 
Operands,  multiple,  5-38 
Operate  Instructions,  C-ll 
Operation, 

foreground/background ,  1-1 
single-job,  1-1 
Operations  on  files,  4-2 
magtape  and  cassette,  4-4 
Operator 

characters,  5-8 
field,  5-3 
Operators , 

binary,  5-8,  5-18 
unary,  5-8,  5-45,  5-50 
Optimizing  device  motion,  A-14 
Optional 

characters,  2-14 
hardware  devices,  1-5 
Output , 

filenames,  4-1 
format,  K-2 
list,  2-11 
ring  buffer,  H-5 


Packed  image  transfer,  J-2 
Page,  3-1 

eject,  5-36,  5-61 
headings,  5-34 
.PAGE  directive,  5-36 
PAL-11R  directive,  5-59 
PAL-11S  conditional  assembly 
directive,  5-59 
Parameter  list,  2-30 
Parameters  used  as  arguments,  E-l 
Passing  switch  information,  9-35 

9-38 

PATCH  utility  program,  1-4,  L-l 
commands,  L-2 
command  summary,  B-16 
error  messages,  L-7 
examples,  L-4 
PATCH, 

assembling  and  linking,  A-20 
calling  and  using,  L-l 
Patching, 

libraries,  M-l 
new  files,  L-2 
OBJ  files,  M-l 
PATCHO,  1-4 
commands,  M-l 
command  summary,  B-17 
error  messages,  M-7 
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examples,  M-5 
limitations,  M-5 
run-time  error  messages,  M-8 
PATCHO , 

calling  and  using,  M-l 
compiling  and  linking,  A-20 
PDP-11  DOS/BATCH  DECtape,  J-l 
Percent  (%)  character,  5-12 
Peripheral  Interchange  Program, 
(PIP) ,  see  PIP 
Permanent , 

device  names,  2-5 
files,  2-20,  9-13 
Permanent  Symbol  Table,  5-9 
Physical  block  numbers,  1-2 
Physical  device,  2-19,  9-5 
names,  2-4 

PIC  (position  independent  code) , 
8-18,  9-21 

PIP  (Peripheral  Interchange  Pro¬ 
gram)  ,  1-4,  4-1 
copy  operations,  4-9 
error  messages,  4-24 
magtape  or  cassette  operations, 
4-4 

switches,  4-2,  4-3 
switch  summary,  B-9 
warning  messages,  4-25 
PIP, 

assembling  and  linking,  A-19 
calling  and  using,  4-1 
POINT  Command,  M-2 
Pointer  location,  3-3 
Pointer  relocation  commands,  3-16 
for  Editor,  B-6 
Position  command,  3-20 
Position  independent  code,  (PIC), 
8-18,  9-21 
Positive, 

arguments,  3-7,  4-5 
numbers,  5-17 

Power  line  synchronization 
feature,  N-ll 
PP.SYS,  A- 3 

PR  (High-Speed  Paper  Tape  Reader) , 
H-5 

•PRINT  directive,  5-71 

•PRINT  request,  9-63 

Printout  formats,  8-5 

Priorities,  Interrupt,  H-l 

Priority,  C-18 

Proceed  command,  8-12 

Proceed  count,  8-13 

Processor  Status,  8-1 

Program  Boundaries  directive,  5-51 

Program, 

counter,  5-20,  8-8 
development  aids,  1-2 
execution,  8-12 
runaway,  8-23 
section  directives,  5-51 
section  names,  5r53 
sections,  absolute  and 
relocatable,  6-4 


Program  starting  commands,  2-32 
R,  2-33 
REENTER,  2-34 
RUN,  2-32 
START,  2-33 

Programmed  requests,  2-7,  9-1 
format,  9-2 
summary,  E-l 
usage,  9-25 
Programming 

considerations,  8-20 
conventions,  H-l 
errors,  1-3 

Prompting  characters,  2-4 

•PROTECT  request,  9-64,  H-3 

PR. SYS,  A- 3 

•PURGE  request,  9-65 

Purging  an  inactive  channel,  9-65 


QCBOOT ,  A- 6,  A- 7 
. QSET  request,  9-65 
Quantities,  absolute,  5-17 
Queue  element,  9-61 


•RADIX  directive,  5-44 
Radix, 

binary,  5-17,  5-45 
decimal,  5-17,  5-45 
octal,  5-17,  5-45 
Radix, 

control,  5-44 

specification  characters,  5-45 
Radix  -50, 

character  set,  C-3 
equivalents,  C-4 
mode,  8-10 
notation,  5-36 
terminators,  8-11 
. RAD 50  directive,  5-43 
Random  access, 

devices,  4-8,  6-1 
file  capabilities,  F-l 
R  Command,  2-33 
. RCTRLO  request,  9-67 
. RCVD  reguest,  9-68 
. RCVDC  request,  9-69 
. RCVDW  request,  9-69 
READ  command,  3-12 
•READ  request,  9-71 
. READC  request,  9-72  < 

. READW  request,  9-73  aaP  - 
READ/WRITE  handler  fun^^n,  ...-9 
Real  arguments,  5-63 
Re-assembling,  1-3  * 

Rebooting  the  system,  4-19 
Receiving  data,  9-68 
Reclaiming  memory,  2-22 
Reconfiguration,  1-5 
Record,  H-9 

Recovering  files,  4-14 
Recovery  from  Bad  Blocks, 

4-21 


% 
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Recovery  procedures  during  output 
operations,  4-8 

Recurring  coding  sequence,  5-60 
Recursive  macros,  10-2 
Reducing  disk  fragmentation,  4-12 
Re-editing,  1-3 
Reenter  bit,  2-34,  9-7 
REENTER  command,  2-34,  3-2 
Reference  line,  K-3 
. REGDEF ,  macro  call,  9-22 
Region  number,  6-13 
Region,  overlay,  6-10,  6-14 
Register  Deferred  Mode,  5-21 
Register, 

destination,  C-14 
expression,  5-20,  C-5 
mnemonic,  9-3 
mode,  5-21 
symbols,  5-11,  5-12 
Register-Offset,  C-14 
Registers , 

console  terminal  control  and 
status,  9-12 
constant,  8-16 
relocation,  L-l 

Reinitializing  monitor  tables, 
4-20 


8-9 

5-25 


9-74 


2-3 


Relative, 

branch,  8-15 
branch  offset, 
deferred  mode, 
mode,  5-24 
.RELEAS  request. 

Releasing  USR  from  memory,  9-57 
REL  format,  6-1 
output  file,  6-2 
switch,  6-23 
Relocatable,  1-2,  5-3 
expressions,  5-18,  8-4 
image  file,  2-3 
image  format  (.REL) 
object  module,  8-1 
Relocation,  8-4 
base,  2-28 
bias,  8-4,  8-17 
calculators,  8-18 
constant,  5-3 
directory,  7-14 
register,  commands ,  8-17 
registers,  8-6,  L-l 
Relocation  and  Linking,  5-19 
.REMOV,  N-9 
RemoviJ**p» 

hand*le»s  from  memory,  9-74 
logical  assignments,  2-19 
terminated  jobs,  2-22 
Rename  operation,  4-15 
.RENAME  request,  9-75 
.REOPEN  request,  9-77 
Repeat  block,  5-73 
Repeat  counts,  8-23 
Replace  switch,  7-5 
Replacement  file,  4-8 


.REPT  directive. 

Requests 

for  Data  Transfer,  9-14 
for  File  Manipulation,  9-14 
for  Miscellaneous  Services, 
requiring  the  USR,  9-19 
Requests,  programmed,  9-1 
Requests , 

.CDFN 

.CHAIN,  9-27 
. CHCOPY,  9-28 
.CLOSE,  9-30 
. CMKT ,  9-31 
. CNTXSW ,  9-32 
.CSIGEN ,  9-33 
.CSISPC,  9-36 
. CSTAT ,  9-41 
.DELETE,  9-42 
.DEVICE,  9-44 
. DSTATUS ,  9-45 
.ENTER,  9-47 
.EXIT,  9-49 
.FETCH,  9-50 
. GTIM,  9-51 
. GTJB,  9-52 
.HERR,  9-53 
.HRESET,  9-55 
•LOCK,  9-56 
.LOOKUP,  9-58 
. MRKT ,  9-60 
.MWAIT,  9-62 
.PRINT,  9-63 
.PROTECT,  9-64 
.PURGE,  9-65 
. QSET ,  9-65 
. RCTRLO ,  9-67 
. RCVD ,  9-68 
. RCVDC ,  9-69 
.RCVDW,  9-69 
.READ,  9-71 
. READC ,  9-72 
. RE ADW ,  9-73 
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